memgit 0.8.1__tar.gz → 0.9.1__tar.gz

{memgit-0.8.1 → memgit-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgit
-Version: 0.8.1
+Version: 0.9.1
 Summary: Git for AI memory — version-controlled context persistence across Claude, GPT, Gemini, Cursor, Windsurf, and more
 License: MIT
 Project-URL: Homepage, https://memgit.dev
@@ -36,6 +36,8 @@ Dynamic: license-file
   <img src="assets/logo.png" alt="memgit logo" width="120" />
 </p>
 
+<!-- mcp-name: dev.memgit/memgit -->
+
 # memgit — git for AI memory
 
 **Your AI assistants forget everything when the session ends. memgit fixes that.**
@@ -44,7 +46,7 @@ Version-controlled, cross-AI context that persists, diffs, rolls back, and syncs
 
 [![PyPI](https://img.shields.io/pypi/v/memgit)](https://pypi.org/project/memgit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-404%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-431%20passing-brightgreen)](tests/)
 
 ---
 
@@ -296,6 +298,23 @@ Since 0.8.0 it also **starts itself**: a project's first guide is created automa
 
 ---
 
+## Backups that actually happen
+
+memgit's premise is that the AI is the operator — but backup used to require a human to remember `memgit git init --remote <url>` and keep pushing. On this project's own store that meant 1,734 memories on one disk with no copy anywhere, five weeks in. A maintenance task that needs a human command is a task that will not happen.
+
+Since 0.9.0 it runs itself, at the end of a session, with the safety boundary drawn at **network egress rather than effort**:
+
+- **Local destinations are automatic** — a cloud-synced folder you already have (iCloud, Dropbox, Google Drive, OneDrive) or an external volume. memgit copies files; it opens no connection and signs up for no service. Your existing sync client does the rest.
+- **A git remote is pushed to only if you already configured one.** memgit never invents a remote, never creates a repository, and never sends memories to a host you did not choose — memories can contain credentials, and convenience is not a reason to publish them somewhere you never picked.
+
+The backup is a single `memgit-store.tar.gz`, not a directory tree: a 203 MB store is 10,295 small object files, and giving a sync client 10k files to reconcile every time is how you get a sync client that never finishes. It is staged and renamed atomically, keeping the old copy until the new one lands — an interrupted backup must never leave a corrupt file where a good one used to be.
+
+```bash
+memgit backup status     # where the last copy went, and what else is available
+```
+
+---
+
 ## Ranking you can prove
 
 Retrieval quality used to be adjusted on intuition. `memgit eval` replaces that with a measurement, using two frozen sets mined from the store itself:
@@ -348,6 +367,12 @@ memgit core heal                  # self-repair a guide that has drifted
                                   # (a project's FIRST guide is created automatically
                                   #  once it holds 5+ memories — no command needed)
 
+# Durability — automatic, no human command required
+memgit backup status              # last copy, staleness, available destinations
+memgit backup now                 # force one immediately
+memgit backup set <path>          # pin a destination
+memgit backup off / on            # control the automatic path
+
 # Retrieval evaluation — prove a ranking change helped
 memgit eval mine                  # freeze a regression set from real recall events
 memgit eval mine --synthetic      # non-circular set: query each memory by its own `why`
@@ -473,7 +498,7 @@ git clone https://github.com/code4161/memgit.git
 cd memgit
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
-pytest    # 404 tests, all passing, < 5 seconds
+pytest    # 431 tests, all passing, < 5 seconds
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -508,6 +533,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 - [x] `memgit eval` — measured retrieval quality, real + non-circular sets (v0.8.0)
 - [x] Usage-aware ranking — the recall ledger feeds relevance, not just the guide (v0.8.0)
 - [x] Automatic core-guide bootstrap — the self-improving loop starts itself (v0.8.0)
+- [x] Automatic off-machine backup — no human command required (v0.9.0)
 - [ ] JetBrains plugin (Phase 3)
 - [ ] Semantic search via embeddings — gated on `memgit eval` showing a real gain (Phase 4)
 - [ ] Public benchmark numbers (LongMemEval, LoCoMo) (Phase 4)

{memgit-0.8.1 → memgit-0.9.1}/README.md

@@ -2,6 +2,8 @@
   <img src="assets/logo.png" alt="memgit logo" width="120" />
 </p>
 
+<!-- mcp-name: dev.memgit/memgit -->
+
 # memgit — git for AI memory
 
 **Your AI assistants forget everything when the session ends. memgit fixes that.**
@@ -10,7 +12,7 @@ Version-controlled, cross-AI context that persists, diffs, rolls back, and syncs
 
 [![PyPI](https://img.shields.io/pypi/v/memgit)](https://pypi.org/project/memgit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-404%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-431%20passing-brightgreen)](tests/)
 
 ---
 
@@ -262,6 +264,23 @@ Since 0.8.0 it also **starts itself**: a project's first guide is created automa
 
 ---
 
+## Backups that actually happen
+
+memgit's premise is that the AI is the operator — but backup used to require a human to remember `memgit git init --remote <url>` and keep pushing. On this project's own store that meant 1,734 memories on one disk with no copy anywhere, five weeks in. A maintenance task that needs a human command is a task that will not happen.
+
+Since 0.9.0 it runs itself, at the end of a session, with the safety boundary drawn at **network egress rather than effort**:
+
+- **Local destinations are automatic** — a cloud-synced folder you already have (iCloud, Dropbox, Google Drive, OneDrive) or an external volume. memgit copies files; it opens no connection and signs up for no service. Your existing sync client does the rest.
+- **A git remote is pushed to only if you already configured one.** memgit never invents a remote, never creates a repository, and never sends memories to a host you did not choose — memories can contain credentials, and convenience is not a reason to publish them somewhere you never picked.
+
+The backup is a single `memgit-store.tar.gz`, not a directory tree: a 203 MB store is 10,295 small object files, and giving a sync client 10k files to reconcile every time is how you get a sync client that never finishes. It is staged and renamed atomically, keeping the old copy until the new one lands — an interrupted backup must never leave a corrupt file where a good one used to be.
+
+```bash
+memgit backup status     # where the last copy went, and what else is available
+```
+
+---
+
 ## Ranking you can prove
 
 Retrieval quality used to be adjusted on intuition. `memgit eval` replaces that with a measurement, using two frozen sets mined from the store itself:
@@ -314,6 +333,12 @@ memgit core heal                  # self-repair a guide that has drifted
                                   # (a project's FIRST guide is created automatically
                                   #  once it holds 5+ memories — no command needed)
 
+# Durability — automatic, no human command required
+memgit backup status              # last copy, staleness, available destinations
+memgit backup now                 # force one immediately
+memgit backup set <path>          # pin a destination
+memgit backup off / on            # control the automatic path
+
 # Retrieval evaluation — prove a ranking change helped
 memgit eval mine                  # freeze a regression set from real recall events
 memgit eval mine --synthetic      # non-circular set: query each memory by its own `why`
@@ -439,7 +464,7 @@ git clone https://github.com/code4161/memgit.git
 cd memgit
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
-pytest    # 404 tests, all passing, < 5 seconds
+pytest    # 431 tests, all passing, < 5 seconds
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -474,6 +499,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 - [x] `memgit eval` — measured retrieval quality, real + non-circular sets (v0.8.0)
 - [x] Usage-aware ranking — the recall ledger feeds relevance, not just the guide (v0.8.0)
 - [x] Automatic core-guide bootstrap — the self-improving loop starts itself (v0.8.0)
+- [x] Automatic off-machine backup — no human command required (v0.9.0)
 - [ ] JetBrains plugin (Phase 3)
 - [ ] Semantic search via embeddings — gated on `memgit eval` showing a real gain (Phase 4)
 - [ ] Public benchmark numbers (LongMemEval, LoCoMo) (Phase 4)

{memgit-0.8.1 → memgit-0.9.1}/memgit/__init__.py

@@ -1,3 +1,3 @@
 """memgit — git for AI memory."""
 
-__version__ = "0.8.1"
+__version__ = "0.9.1"

memgit-0.9.1/memgit/backup.py

@@ -0,0 +1,377 @@
+"""Durability that does not wait for a human.
+
+memgit's operating premise is that the AI is the operator. Backup was the one
+place that premise broke: off-machine safety required someone to remember to
+run `memgit git init --remote <url>` and then keep pushing. On a store audited
+at 1,734 memories across five weeks of daily use, it had never been run once —
+the entire memory set existed on a single disk with no copy anywhere.
+
+A maintenance task that needs a human command is a maintenance task that will
+not happen. So this module makes durability automatic, with the safety boundary
+drawn at *network egress* rather than at *effort*:
+
+  * LOCAL destinations (a cloud-synced folder the user already has, an external
+    volume) are used AUTOMATICALLY. memgit copies files; it opens no
+    connection and signs up for no service. Whatever sync client the user
+    already trusts does the rest.
+  * A GIT REMOTE is pushed to automatically ONLY when the user has already
+    configured one. memgit never invents a remote, never creates a repository,
+    and never sends memories to a host the user has not already chosen.
+
+That distinction matters because memories are not neutral text: a prior audit
+on this very store found client credentials among them. Convenience is not a
+reason to publish someone's private notes to a service they never picked.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+#: Backup state lives beside the store, not inside the object DB — it is
+#: operational metadata, not memory, and must not churn the index.
+_STATE = 'backup.json'
+
+#: A backup older than this is stale enough to redo on the next quiet moment.
+STALE_AFTER_HOURS = 24
+
+#: Skipped when mirroring: caches are per-session scratch, and the flat
+#: memories/ export is regenerated on demand. Everything needed to reconstruct
+#: the store (objects, refs, index, HEAD, config) is copied.
+_MIRROR_SKIP = {'cache'}
+
+
+@dataclass
+class Destination:
+    kind: str            # synced | volume | remote | path
+    label: str           # human-readable, e.g. "iCloud Drive"
+    target: str          # filesystem path, or git remote name
+    auto_ok: bool        # may be used without asking (no new network egress)
+
+
+@dataclass
+class BackupState:
+    last_ok: Optional[str] = None       # ISO timestamp
+    last_target: Optional[str] = None
+    last_kind: Optional[str] = None
+    last_error: Optional[str] = None
+    memories: int = 0
+    disabled: bool = False
+    pinned: Optional[str] = None        # operator-chosen destination path
+
+
+def _state_path(repo) -> Path:
+    return repo.path / _STATE
+
+
+def read_state(repo) -> BackupState:
+    try:
+        raw = json.loads(_state_path(repo).read_text(encoding='utf-8'))
+        return BackupState(**{k: v for k, v in raw.items()
+                              if k in BackupState.__dataclass_fields__})
+    except (OSError, json.JSONDecodeError, TypeError):
+        return BackupState()
+
+
+def write_state(repo, state: BackupState) -> None:
+    try:
+        _state_path(repo).write_text(json.dumps(asdict(state), indent=1),
+                                     encoding='utf-8')
+    except OSError:
+        pass
+
+
+# ── destination discovery ─────────────────────────────────────────────────────
+
+def _synced_folder_candidates(home: Path) -> list[tuple[str, Path]]:
+    """Cloud-sync roots this machine already has. Presence is the whole test —
+    if the directory exists the user already uses (and trusts) that service."""
+    return [
+        ('iCloud Drive', home / 'Library' / 'Mobile Documents' / 'com~apple~CloudDocs'),
+        ('Dropbox', home / 'Dropbox'),
+        ('Google Drive', home / 'Library' / 'CloudStorage'),
+        ('OneDrive', home / 'OneDrive'),
+        ('Sync', home / 'Sync'),
+    ]
+
+
+def detect_destinations(repo, home: Optional[Path] = None) -> list[Destination]:
+    """Every viable backup target, best-first.
+
+    Ordering is deliberate: a configured git remote is the user's own explicit
+    choice and wins; then cloud-synced folders (genuinely off-machine); then
+    external volumes (off-disk, but only as good as the drive being attached).
+    """
+    home = home or Path.home()
+    out: list[Destination] = []
+
+    remote = _configured_remote(repo)
+    if remote:
+        out.append(Destination('remote', f'git remote ({remote})', remote,
+                               auto_ok=True))
+
+    for label, path in _synced_folder_candidates(home):
+        if path.is_dir():
+            out.append(Destination('synced', label, str(path / 'memgit-backup'),
+                                   auto_ok=True))
+
+    for vol in _external_volumes():
+        out.append(Destination('volume', f'volume {vol.name}',
+                               str(vol / 'memgit-backup'), auto_ok=True))
+
+    return out
+
+
+def _external_volumes() -> list[Path]:
+    """Mounted volumes that are not the boot disk."""
+    vols = Path('/Volumes')
+    if not vols.is_dir():
+        return []
+    out = []
+    try:
+        for v in sorted(vols.iterdir()):
+            try:
+                if v.is_dir() and not v.is_symlink() and os.access(v, os.W_OK):
+                    out.append(v)
+            except OSError:
+                continue
+    except OSError:
+        return []
+    return out
+
+
+def _configured_remote(repo) -> Optional[str]:
+    """Name of a git remote already configured on the store, or None.
+
+    memgit NEVER creates one. A remote here means the user chose a host.
+    """
+    root = repo.path.parent
+    if not (root / '.git').exists():
+        return None
+    try:
+        r = subprocess.run(['git', 'remote'], cwd=root, capture_output=True,
+                           text=True, timeout=10)
+        names = [n.strip() for n in r.stdout.splitlines() if n.strip()]
+        return names[0] if names else None
+    except Exception:
+        return None
+
+
+# ── running a backup ──────────────────────────────────────────────────────────
+
+#: Archive name inside the destination directory. Fixed, not timestamped:
+#: an unbounded pile of dated archives in someone's iCloud is a bug, and
+#: memgit's own history already provides point-in-time recovery.
+ARCHIVE_NAME = 'memgit-store.tar.gz'
+
+
+def mirror_store(repo, target: Path) -> int:
+    """Write the store to `target` as ONE compressed archive. Returns file count.
+
+    An archive rather than a directory tree, because the realistic destination
+    is a cloud-synced folder: the audited store is 203 MB across 10,295 small
+    object files, and handing a sync client 10k files to reconcile on every
+    backup is how you get a sync client that never finishes. One file also
+    makes the swap below genuinely atomic.
+
+    Written to a staging name and renamed over the target, with the old copy
+    kept until the new one lands — an interrupted backup must never destroy the
+    good copy it was replacing. That failure mode does not lose data loudly; it
+    leaves a corrupt file where safety used to be, which is worse.
+    """
+    import tarfile
+
+    target_dir = Path(target)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    final = target_dir / ARCHIVE_NAME
+    staging = target_dir / (ARCHIVE_NAME + '.incoming')
+    previous = target_dir / (ARCHIVE_NAME + '.previous')
+    staging.unlink(missing_ok=True)
+
+    src_root = repo.path.parent
+    files = 0
+
+    def _filter(info: 'tarfile.TarInfo'):
+        nonlocal files
+        parts = Path(info.name).parts
+        if any(p in _MIRROR_SKIP for p in parts):
+            return None
+        if info.issym() or info.islnk():
+            return None
+        if info.isfile():
+            files += 1
+        return info
+
+    with tarfile.open(staging, 'w:gz', compresslevel=6) as tar:
+        tar.add(src_root, arcname='memgit-store', filter=_filter)
+
+    (target_dir / 'RESTORE.txt').write_text(
+        f'memgit store backup\n'
+        f'source  : {src_root}\n'
+        f'written : {datetime.now(timezone.utc).isoformat()}\n'
+        f'files   : {files}\n'
+        f'archive : {ARCHIVE_NAME}\n\n'
+        f'To restore:\n'
+        f'  tar -xzf {ARCHIVE_NAME}\n'
+        f'  rm -rf ~/.claude/memgit-store\n'
+        f'  mv memgit-store ~/.claude/memgit-store\n'
+        f'  memgit fsck\n',
+        encoding='utf-8')
+
+    previous.unlink(missing_ok=True)
+    if final.exists():
+        final.rename(previous)
+    staging.rename(final)
+    previous.unlink(missing_ok=True)
+    return files
+
+
+def push_remote(repo, remote: str) -> None:
+    """Export flat memories, commit, and push to an ALREADY-configured remote."""
+    root = repo.path.parent
+    repo.write_flat()
+    subprocess.run(['git', 'add', '-A'], cwd=root, capture_output=True, timeout=60)
+    subprocess.run(
+        ['git', 'commit', '-m',
+         f'memgit backup {datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")}'],
+        cwd=root, capture_output=True, timeout=60)
+    r = subprocess.run(['git', 'push', remote, 'HEAD'], cwd=root,
+                       capture_output=True, text=True, timeout=180)
+    if r.returncode != 0:
+        raise RuntimeError((r.stderr or 'git push failed').strip()[:300])
+
+
+def run_backup(repo, dest: Optional[Destination] = None,
+               home: Optional[Path] = None) -> tuple[bool, str]:
+    """Back the store up to `dest` (or the best automatic one). (ok, message)."""
+    state = read_state(repo)
+    if dest is None:
+        if state.pinned:
+            dest = Destination('path', 'pinned', state.pinned, auto_ok=True)
+        else:
+            options = [d for d in detect_destinations(repo, home) if d.auto_ok]
+            dest = options[0] if options else None
+    if dest is None:
+        return False, ('no backup destination available — no git remote is '
+                       'configured and no cloud-synced folder or external '
+                       'volume was found')
+
+    try:
+        if dest.kind == 'remote':
+            push_remote(repo, dest.target)
+            detail = f'pushed to {dest.label}'
+        else:
+            n = mirror_store(repo, Path(dest.target))
+            detail = f'mirrored {n} files to {dest.target}'
+    except Exception as e:                                  # noqa: BLE001
+        state.last_error = str(e)[:300]
+        write_state(repo, state)
+        return False, f'backup failed: {state.last_error}'
+
+    try:
+        count = len(repo.list())
+    except Exception:
+        count = state.memories
+    state.last_ok = datetime.now(timezone.utc).isoformat()
+    state.last_target = dest.target
+    state.last_kind = dest.kind
+    state.last_error = None
+    state.memories = count
+    write_state(repo, state)
+    return True, detail
+
+
+# ── the automatic path ────────────────────────────────────────────────────────
+
+def hours_since_backup(repo, now: Optional[datetime] = None) -> Optional[float]:
+    """Hours since the last successful backup, or None if there has never been one."""
+    state = read_state(repo)
+    if not state.last_ok:
+        return None
+    try:
+        last = datetime.fromisoformat(state.last_ok)
+    except ValueError:
+        return None
+    if last.tzinfo is None:
+        last = last.replace(tzinfo=timezone.utc)
+    now = now or datetime.now(timezone.utc)
+    return (now - last).total_seconds() / 3600.0
+
+
+def is_stale(repo, now: Optional[datetime] = None) -> bool:
+    age = hours_since_backup(repo, now)
+    return age is None or age >= STALE_AFTER_HOURS
+
+
+def auto_backup_allowed(repo) -> bool:
+    """Whether the UNATTENDED path may run for this store.
+
+    Guard against a class of bug found the hard way: a test that exercised the
+    end-of-session sync path fired a real backup into the developer's actual
+    iCloud folder, because destination discovery reads the true home directory
+    while the store was a temp path. Anything that writes outside the store,
+    unprompted, must be certain it is operating on the user's real store.
+
+    `MEMGIT_STORE` is set by the test suite (and by anyone pointing memgit at a
+    scratch store), so it is exactly the signal for "this is not the store whose
+    durability I am responsible for". Explicit `memgit backup now` is unaffected
+    — that is a human or agent asking on purpose.
+    """
+    if os.environ.get('MEMGIT_STORE'):
+        return False
+    if os.environ.get('PYTEST_CURRENT_TEST'):
+        return False
+    return True
+
+
+def maybe_auto_backup(repo, home: Optional[Path] = None,
+                      now: Optional[datetime] = None) -> Optional[str]:
+    """Back up if it is due and a safe destination exists. Silent and best-effort.
+
+    Called from the end-of-session sync path, alongside the other housekeeping
+    the AI operator never has to think about. Returns a short message when a
+    backup ran, else None. Never raises into a hook.
+    """
+    try:
+        if not auto_backup_allowed(repo):
+            return None
+        state = read_state(repo)
+        if state.disabled:
+            return None
+        if not is_stale(repo, now):
+            return None
+        ok, msg = run_backup(repo, home=home)
+        return msg if ok else None
+    except Exception:                                       # noqa: BLE001
+        return None
+
+
+def status_line(repo, now: Optional[datetime] = None) -> Optional[str]:
+    """One line for the resume digest when durability needs attention.
+
+    Silent when a recent backup exists — a warning that fires every session is
+    a warning that gets ignored. Loud, with the exact call to make, when there
+    is no copy at all: that is the state where a disk failure is total loss.
+    """
+    state = read_state(repo)
+    if state.disabled:
+        return None
+    age = hours_since_backup(repo, now)
+    if age is None:
+        try:
+            n = len(repo.list())
+        except Exception:
+            n = 0
+        if n < 20:
+            return None      # nothing worth protecting yet
+        # Terse on purpose. This rides a hard-budgeted digest injected every
+        # session; the reasoning and the destination list live in
+        # `memgit backup status`, one command away.
+        return f'no backup — {n} memories on one disk. `memgit backup now`'
+    if age >= STALE_AFTER_HOURS * 7:
+        return f'last backup {int(age / 24)}d ago. `memgit backup now`'
+    return None

{memgit-0.8.1 → memgit-0.9.1}/memgit/cli.py

@@ -485,6 +485,13 @@ def _maybe_auto_core(repo) -> None:
         repo.gc_caches()
     except Exception:
         pass
+    # Durability, unattended. A backup that needs someone to remember a command
+    # is a backup that does not exist — measured: zero in five weeks of use.
+    try:
+        from .backup import maybe_auto_backup
+        maybe_auto_backup(repo)
+    except Exception:
+        pass
 
 
 @core.command('refresh')
@@ -715,6 +722,8 @@ def resume(checkpoints, recent, plain, fmt_json, project):
                       f'[dim](memgit search "<topic>")[/dim]')
     if ctx.get('maintenance'):
         console.print(f'\n[yellow]maintenance:[/yellow] {ctx["maintenance"]}')
+    if ctx.get('durability'):
+        console.print(f'\n[red]durability:[/red] {ctx["durability"]}')
     console.print()
 
 
@@ -855,6 +864,12 @@ def _render_resume_plain(ctx: dict) -> str:
     if ctx.get('maintenance'):
         lines.append('')
         lines.append(f'## Maintenance needed\n- {ctx["maintenance"]}')
+    # Durability is separate from maintenance and never trimmed: a store with
+    # no copy anywhere is one disk failure from total loss, and the operator
+    # who has to act on it is the agent reading this digest.
+    if ctx.get('durability'):
+        lines.append('')
+        lines.append(f'## Durability\n- {ctx["durability"]}')
     if ctx.get('project_is_new'):
         lines.append('')
         lines.append(
@@ -1963,6 +1978,109 @@ def metrics(fmt_json, reset):
     console.print()
 
 
+@cli.group(invoke_without_command=True)
+@click.pass_context
+def backup(ctx):
+    """Off-machine durability — automatic, no human command required.
+
+    Local destinations (a cloud-synced folder you already have, an external
+    volume) are used automatically: memgit copies files and opens no network
+    connection. A git remote is pushed to only if you have already configured
+    one — memgit never invents a remote or creates a repository, because
+    memories can contain credentials and must not land on a service you did
+    not choose.
+    """
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(backup_status)
+
+
+@backup.command('status')
+def backup_status():
+    """Where the last copy went, how old it is, and what else is available."""
+    repo = _require_repo()
+    from .backup import (read_state, detect_destinations, hours_since_backup,
+                         STALE_AFTER_HOURS)
+    state = read_state(repo)
+    age = hours_since_backup(repo)
+
+    if state.disabled:
+        console.print('[yellow]backup disabled[/yellow] — re-enable with '
+                      '`memgit backup on`')
+    elif age is None:
+        console.print(f'[red]no backup has ever run[/red] — '
+                      f'{len(repo.list())} memories exist on one disk')
+    else:
+        colour = 'green' if age < STALE_AFTER_HOURS else 'yellow'
+        when = f'{age:.1f}h ago' if age < 48 else f'{age / 24:.1f}d ago'
+        console.print(f'[{colour}]last backup {when}[/{colour}]  '
+                      f'[dim]{state.memories} memories → {state.last_target}[/dim]')
+    if state.last_error:
+        console.print(f'  [red]last error:[/red] {state.last_error}')
+
+    dests = detect_destinations(repo)
+    console.print()
+    if not dests:
+        console.print('[yellow]no destination available[/yellow] — no git remote '
+                      'configured, no cloud-synced folder or external volume found.')
+        console.print('[dim]Set one explicitly: `memgit backup set <path>`[/dim]')
+        return
+    console.print('[bold]Available destinations[/bold] [dim](best first)[/dim]')
+    for d in dests:
+        mark = '[green]auto[/green]' if d.auto_ok else '[yellow]ask[/yellow]'
+        console.print(f'  {mark}  {d.label:24} [dim]{d.target}[/dim]')
+
+
+@backup.command('now')
+@click.option('--to', 'to_path', default=None,
+              help='Explicit destination path (overrides auto-detection)')
+def backup_now(to_path):
+    """Back up immediately."""
+    repo = _require_repo()
+    from .backup import run_backup, Destination
+    dest = Destination('path', 'explicit', to_path, True) if to_path else None
+    ok, msg = run_backup(repo, dest)
+    if ok:
+        console.print(f'[green]backup ok[/green] — {msg}')
+    else:
+        err.print(f'[red]{msg}[/red]')
+        sys.exit(1)
+
+
+@backup.command('set')
+@click.argument('path')
+def backup_set(path):
+    """Pin a destination directory for every future backup."""
+    repo = _require_repo()
+    from .backup import read_state, write_state
+    state = read_state(repo)
+    state.pinned = str(Path(path).expanduser())
+    state.disabled = False
+    write_state(repo, state)
+    console.print(f'[green]backup destination pinned[/green] → {state.pinned}')
+
+
+@backup.command('off')
+def backup_off():
+    """Stop automatic backups."""
+    repo = _require_repo()
+    from .backup import read_state, write_state
+    state = read_state(repo)
+    state.disabled = True
+    write_state(repo, state)
+    console.print('[yellow]automatic backup disabled[/yellow]')
+
+
+@backup.command('on')
+def backup_on():
+    """Resume automatic backups."""
+    repo = _require_repo()
+    from .backup import read_state, write_state
+    state = read_state(repo)
+    state.disabled = False
+    write_state(repo, state)
+    console.print('[green]automatic backup enabled[/green]')
+
+
 @cli.group(invoke_without_command=True)
 @click.pass_context
 def eval(ctx):

{memgit-0.8.1 → memgit-0.9.1}/memgit/repo.py

@@ -996,8 +996,17 @@ class Repository:
             'entity_index': topics,
             'core_missing': core_missing,
             'maintenance': self.maintenance_hint(count),
+            'durability': self._durability_hint(),
         }
 
+    def _durability_hint(self) -> Optional[str]:
+        """Backup warning for the digest, or None while safe. Never raises."""
+        try:
+            from .backup import status_line
+            return status_line(self)
+        except Exception:
+            return None
+
     def _scoped_checkpoints(self, checkpoints: int,
                             project: Optional[str],
                             all_mnemonics: list[Mnemonic]) -> list[Checkpoint]:

{memgit-0.8.1 → memgit-0.9.1}/memgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgit
-Version: 0.8.1
+Version: 0.9.1
 Summary: Git for AI memory — version-controlled context persistence across Claude, GPT, Gemini, Cursor, Windsurf, and more
 License: MIT
 Project-URL: Homepage, https://memgit.dev
@@ -36,6 +36,8 @@ Dynamic: license-file
   <img src="assets/logo.png" alt="memgit logo" width="120" />
 </p>
 
+<!-- mcp-name: dev.memgit/memgit -->
+
 # memgit — git for AI memory
 
 **Your AI assistants forget everything when the session ends. memgit fixes that.**
@@ -44,7 +46,7 @@ Version-controlled, cross-AI context that persists, diffs, rolls back, and syncs
 
 [![PyPI](https://img.shields.io/pypi/v/memgit)](https://pypi.org/project/memgit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-404%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-431%20passing-brightgreen)](tests/)
 
 ---
 
@@ -296,6 +298,23 @@ Since 0.8.0 it also **starts itself**: a project's first guide is created automa
 
 ---
 
+## Backups that actually happen
+
+memgit's premise is that the AI is the operator — but backup used to require a human to remember `memgit git init --remote <url>` and keep pushing. On this project's own store that meant 1,734 memories on one disk with no copy anywhere, five weeks in. A maintenance task that needs a human command is a task that will not happen.
+
+Since 0.9.0 it runs itself, at the end of a session, with the safety boundary drawn at **network egress rather than effort**:
+
+- **Local destinations are automatic** — a cloud-synced folder you already have (iCloud, Dropbox, Google Drive, OneDrive) or an external volume. memgit copies files; it opens no connection and signs up for no service. Your existing sync client does the rest.
+- **A git remote is pushed to only if you already configured one.** memgit never invents a remote, never creates a repository, and never sends memories to a host you did not choose — memories can contain credentials, and convenience is not a reason to publish them somewhere you never picked.
+
+The backup is a single `memgit-store.tar.gz`, not a directory tree: a 203 MB store is 10,295 small object files, and giving a sync client 10k files to reconcile every time is how you get a sync client that never finishes. It is staged and renamed atomically, keeping the old copy until the new one lands — an interrupted backup must never leave a corrupt file where a good one used to be.
+
+```bash
+memgit backup status     # where the last copy went, and what else is available
+```
+
+---
+
 ## Ranking you can prove
 
 Retrieval quality used to be adjusted on intuition. `memgit eval` replaces that with a measurement, using two frozen sets mined from the store itself:
@@ -348,6 +367,12 @@ memgit core heal                  # self-repair a guide that has drifted
                                   # (a project's FIRST guide is created automatically
                                   #  once it holds 5+ memories — no command needed)
 
+# Durability — automatic, no human command required
+memgit backup status              # last copy, staleness, available destinations
+memgit backup now                 # force one immediately
+memgit backup set <path>          # pin a destination
+memgit backup off / on            # control the automatic path
+
 # Retrieval evaluation — prove a ranking change helped
 memgit eval mine                  # freeze a regression set from real recall events
 memgit eval mine --synthetic      # non-circular set: query each memory by its own `why`
@@ -473,7 +498,7 @@ git clone https://github.com/code4161/memgit.git
 cd memgit
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
-pytest    # 404 tests, all passing, < 5 seconds
+pytest    # 431 tests, all passing, < 5 seconds
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -508,6 +533,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 - [x] `memgit eval` — measured retrieval quality, real + non-circular sets (v0.8.0)
 - [x] Usage-aware ranking — the recall ledger feeds relevance, not just the guide (v0.8.0)
 - [x] Automatic core-guide bootstrap — the self-improving loop starts itself (v0.8.0)
+- [x] Automatic off-machine backup — no human command required (v0.9.0)
 - [ ] JetBrains plugin (Phase 3)
 - [ ] Semantic search via embeddings — gated on `memgit eval` showing a real gain (Phase 4)
 - [ ] Public benchmark numbers (LongMemEval, LoCoMo) (Phase 4)

{memgit-0.8.1 → memgit-0.9.1}/memgit.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 memgit/__init__.py
+memgit/backup.py
 memgit/cli.py
 memgit/delivery.py
 memgit/evaluate.py
@@ -37,6 +38,7 @@ memgit/cloud/sync.py
 tests/test_accrue.py
 tests/test_advanced.py
 tests/test_aliases.py
+tests/test_backup.py
 tests/test_core.py
 tests/test_delivery.py
 tests/test_setup.py

{memgit-0.8.1 → memgit-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memgit"
-version = "0.8.1"
+version = "0.9.1"
 description = "Git for AI memory — version-controlled context persistence across Claude, GPT, Gemini, Cursor, Windsurf, and more"
 readme = "README.md"
 requires-python = ">=3.11"

memgit-0.9.1/tests/test_backup.py

@@ -0,0 +1,236 @@
+"""v0.9.0 — durability that does not wait for a human.
+
+The premise under test: a maintenance task requiring a human command is a task
+that will not happen (measured — `git init` was never run in five weeks on a
+1,734-memory store). These tests pin the automatic path AND the safety boundary
+that keeps it from being reckless.
+"""
+import os
+import tarfile
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+from memgit.models import Mnemonic
+from memgit.repo import Repository
+
+
+@pytest.fixture
+def repo(tmp_path):
+    r = Repository.init(tmp_path / "store")
+    for i in range(30):
+        r.add(Mnemonic(type_code="lx", slug=f"m{i}", rule=f"lesson number {i}",
+                       timestamp=datetime.now(timezone.utc), project="P"))
+    r.commit(message="seed", trigger="explicit")
+    return r
+
+
+def _fake_home(tmp_path, *names) -> Path:
+    home = tmp_path / "home"
+    for n in names:
+        (home / n).mkdir(parents=True, exist_ok=True)
+    home.mkdir(exist_ok=True)
+    return home
+
+
+# ── destination discovery ────────────────────────────────────────────────────
+
+class TestDestinations:
+    def test_finds_icloud(self, repo, tmp_path):
+        from memgit.backup import detect_destinations
+        home = _fake_home(tmp_path, "Library/Mobile Documents/com~apple~CloudDocs")
+        dests = detect_destinations(repo, home)
+        assert any(d.label == "iCloud Drive" and d.kind == "synced" for d in dests)
+
+    def test_finds_dropbox(self, repo, tmp_path):
+        from memgit.backup import detect_destinations
+        home = _fake_home(tmp_path, "Dropbox")
+        assert any(d.label == "Dropbox" for d in detect_destinations(repo, home))
+
+    def test_no_destinations_when_nothing_present(self, repo, tmp_path, monkeypatch):
+        from memgit import backup
+        monkeypatch.setattr(backup, "_external_volumes", lambda: [])
+        home = _fake_home(tmp_path)
+        assert backup.detect_destinations(repo, home) == []
+
+    def test_never_invents_a_git_remote(self, repo, tmp_path):
+        """memgit must not create a repository or pick a host on the user's
+        behalf — memories can contain credentials."""
+        from memgit.backup import _configured_remote
+        assert _configured_remote(repo) is None
+
+    def test_configured_remote_ranks_first(self, repo, tmp_path, monkeypatch):
+        from memgit import backup
+        monkeypatch.setattr(backup, "_configured_remote", lambda r: "origin")
+        monkeypatch.setattr(backup, "_external_volumes", lambda: [])
+        home = _fake_home(tmp_path, "Dropbox")
+        dests = backup.detect_destinations(repo, home)
+        assert dests[0].kind == "remote"
+
+
+# ── the archive ──────────────────────────────────────────────────────────────
+
+class TestArchive:
+    def test_produces_one_file_not_a_tree(self, repo, tmp_path):
+        """10k small object files into a cloud-sync folder is how you get a
+        sync client that never finishes."""
+        from memgit.backup import mirror_store, ARCHIVE_NAME
+        dest = tmp_path / "dest"
+        mirror_store(repo, dest)
+        assert (dest / ARCHIVE_NAME).is_file()
+        assert not (dest / ".memgit").exists()
+
+    def test_archive_round_trips(self, repo, tmp_path):
+        """The only property that matters: it restores."""
+        from memgit.backup import mirror_store, ARCHIVE_NAME
+        dest = tmp_path / "dest"
+        mirror_store(repo, dest)
+        out = tmp_path / "restored"
+        out.mkdir()
+        with tarfile.open(dest / ARCHIVE_NAME) as tar:
+            tar.extractall(out, filter="data")
+        restored = Repository(out / "memgit-store" / ".memgit")
+        assert len(restored.list()) == 30
+        assert restored.fsck() == []
+
+    def test_cache_is_excluded(self, repo, tmp_path):
+        from memgit.backup import mirror_store, ARCHIVE_NAME
+        (repo.path / "cache" / "recall").mkdir(parents=True, exist_ok=True)
+        (repo.path / "cache" / "recall" / "sess").write_text("junk")
+        dest = tmp_path / "dest"
+        mirror_store(repo, dest)
+        with tarfile.open(dest / ARCHIVE_NAME) as tar:
+            names = tar.getnames()
+        assert not any("/cache/" in n for n in names)
+
+    def test_previous_archive_survives_until_new_one_lands(self, repo, tmp_path):
+        """An interrupted backup must never leave a corrupt file where a good
+        one used to be — that is worse than no backup, because it looks safe."""
+        from memgit.backup import mirror_store, ARCHIVE_NAME
+        dest = tmp_path / "dest"
+        mirror_store(repo, dest)
+        first = (dest / ARCHIVE_NAME).read_bytes()
+        repo.add(Mnemonic(type_code="lx", slug="later", rule="added after",
+                          timestamp=datetime.now(timezone.utc), project="P"))
+        repo.commit(message="more", trigger="explicit")
+        mirror_store(repo, dest)
+        assert (dest / ARCHIVE_NAME).read_bytes() != first
+        assert not (dest / (ARCHIVE_NAME + ".incoming")).exists()
+        assert not (dest / (ARCHIVE_NAME + ".previous")).exists()
+
+    def test_writes_restore_instructions(self, repo, tmp_path):
+        from memgit.backup import mirror_store
+        dest = tmp_path / "dest"
+        mirror_store(repo, dest)
+        text = (dest / "RESTORE.txt").read_text()
+        assert "tar -xzf" in text and "memgit fsck" in text
+
+
+# ── the automatic path + its safety boundary ─────────────────────────────────
+
+class TestAutoBackup:
+    def test_refuses_to_run_unattended_on_a_scratch_store(self, repo, monkeypatch):
+        """Regression: a test exercising the sync path fired a real backup into
+        the developer's actual iCloud, because discovery reads the true home
+        while the store was a temp path."""
+        from memgit.backup import auto_backup_allowed, maybe_auto_backup
+        monkeypatch.setenv("MEMGIT_STORE", "/tmp/whatever")
+        assert auto_backup_allowed(repo) is False
+        assert maybe_auto_backup(repo) is None
+
+    def test_refuses_under_pytest(self, repo, monkeypatch):
+        from memgit.backup import auto_backup_allowed
+        monkeypatch.delenv("MEMGIT_STORE", raising=False)
+        # PYTEST_CURRENT_TEST is always set while a test is executing
+        assert os.environ.get("PYTEST_CURRENT_TEST")
+        assert auto_backup_allowed(repo) is False
+
+    def test_explicit_backup_is_never_blocked_by_the_guard(self, repo, tmp_path):
+        """`backup now` is someone asking on purpose — the guard is only for
+        the unattended path."""
+        from memgit.backup import run_backup, Destination
+        dest = Destination("path", "explicit", str(tmp_path / "dest"), True)
+        ok, msg = run_backup(repo, dest)
+        assert ok, msg
+
+    def test_staleness(self, repo):
+        from memgit.backup import (read_state, write_state, is_stale,
+                                   hours_since_backup, STALE_AFTER_HOURS)
+        assert is_stale(repo) is True          # never backed up
+        assert hours_since_backup(repo) is None
+        s = read_state(repo)
+        s.last_ok = datetime.now(timezone.utc).isoformat()
+        write_state(repo, s)
+        assert is_stale(repo) is False
+        s.last_ok = (datetime.now(timezone.utc)
+                     - timedelta(hours=STALE_AFTER_HOURS + 1)).isoformat()
+        write_state(repo, s)
+        assert is_stale(repo) is True
+
+    def test_disabled_state_is_respected(self, repo):
+        from memgit.backup import read_state, write_state, maybe_auto_backup
+        s = read_state(repo)
+        s.disabled = True
+        write_state(repo, s)
+        assert maybe_auto_backup(repo) is None
+
+    def test_state_records_success(self, repo, tmp_path):
+        from memgit.backup import run_backup, Destination, read_state
+        ok, _ = run_backup(repo, Destination("path", "x", str(tmp_path / "d"), True))
+        assert ok
+        s = read_state(repo)
+        assert s.last_ok and s.memories == 30 and s.last_error is None
+
+    def test_failure_is_recorded_not_raised(self, repo, monkeypatch, tmp_path):
+        from memgit import backup
+        def boom(*a, **k):
+            raise OSError("disk gone")
+        monkeypatch.setattr(backup, "mirror_store", boom)
+        ok, msg = backup.run_backup(
+            repo, backup.Destination("path", "x", str(tmp_path / "d"), True))
+        assert ok is False and "disk gone" in msg
+        assert backup.read_state(repo).last_error
+
+
+# ── the digest warning ───────────────────────────────────────────────────────
+
+class TestDurabilityHint:
+    def test_warns_when_no_backup_exists(self, repo):
+        from memgit.backup import status_line
+        line = status_line(repo)
+        assert line and "backup" in line.lower() and "30 memories" in line
+
+    def test_silent_for_a_tiny_store(self, tmp_path):
+        """Nothing worth protecting yet — a warning that always fires is noise."""
+        from memgit.backup import status_line
+        r = Repository.init(tmp_path / "small")
+        r.add(Mnemonic(type_code="lx", slug="one", rule="only one",
+                       timestamp=datetime.now(timezone.utc)))
+        r.commit(message="x", trigger="explicit")
+        assert status_line(r) is None
+
+    def test_silent_right_after_a_backup(self, repo):
+        from memgit.backup import read_state, write_state, status_line
+        s = read_state(repo)
+        s.last_ok = datetime.now(timezone.utc).isoformat()
+        write_state(repo, s)
+        assert status_line(repo) is None
+
+    def test_warns_again_when_very_stale(self, repo):
+        from memgit.backup import read_state, write_state, status_line
+        s = read_state(repo)
+        s.last_ok = (datetime.now(timezone.utc) - timedelta(days=30)).isoformat()
+        write_state(repo, s)
+        line = status_line(repo)
+        assert line and "30d ago" in line
+
+    def test_silent_when_disabled(self, repo):
+        from memgit.backup import read_state, write_state, status_line
+        s = read_state(repo)
+        s.disabled = True
+        write_state(repo, s)
+        assert status_line(repo) is None
+
+    def test_hint_reaches_the_resume_digest(self, repo):
+        assert repo.resume_context().get("durability")

{memgit-0.8.1 → memgit-0.9.1}/tests/test_v060.py

@@ -565,14 +565,47 @@ class TestTokenBudget:
         assert added_tokens <= 250, f"new sections cost ~{added_tokens:.0f} tokens"
 
     def test_resume_bounded_on_large_store(self, repo):
+        """Steady state — a store WITH a backup — must stay under budget.
+
+        This is the case that runs every session for a healthy store, so it is
+        the one the bound has to hold for.
+        """
         from memgit.cli import _format_resume_plain
+        from memgit.backup import read_state, write_state
+        from datetime import datetime, timezone
         self._big_store(repo)
         for i in range(9):
             repo.add(_mk(f"e{i}-status", type_code="tr", rule="state " * 10))
+        state = read_state(repo)
+        state.last_ok = datetime.now(timezone.utc).isoformat()
+        write_state(repo, state)
         text = _format_resume_plain(repo.resume_context())
         approx_tokens = len(text) / 4  # chars/4 heuristic
         assert approx_tokens <= 900, f"digest too big: ~{approx_tokens:.0f} tokens"
 
+    def test_durability_warning_is_cheap_and_self_clearing(self, repo):
+        """With no backup the digest carries a warning; it costs ~20 tokens and
+        disappears the moment a backup exists (including an automatic one), so
+        the steady-state digest is unchanged by this feature."""
+        from memgit.cli import _format_resume_plain
+        from memgit.backup import read_state, write_state
+        from datetime import datetime, timezone
+        self._big_store(repo)
+        for i in range(9):
+            repo.add(_mk(f"e{i}-status", type_code="tr", rule="state " * 10))
+
+        warned = _format_resume_plain(repo.resume_context())
+        assert "backup" in warned.lower()
+        assert len(warned) / 4 <= 930, "the warning itself must stay small"
+
+        state = read_state(repo)
+        state.last_ok = datetime.now(timezone.utc).isoformat()
+        write_state(repo, state)
+        clean = _format_resume_plain(repo.resume_context())
+        assert "Durability" not in clean
+        assert (len(warned) - len(clean)) / 4 <= 30, \
+            "durability warning must cost under ~30 tokens"
+
     def test_server_description_pins_authority_framing(self):
         from memgit.mcp_server import _SERVER_DESCRIPTION, _TYPE_DESCRIPTIONS
         assert "AUTHORITY" in _SERVER_DESCRIPTION