mirror of https://github.com/akitaonrails/ai-memory.git synced 2026-10-02 03:24:46 +08:00

Files

T

Renato JuniorandClaude 7ac4b949a4 docs(backup): recipe + worked example for remote git backup

The docs already tell users that pushing the wiki to a remote git repository
is a supported backup pattern: docs/deploy.md#backups says 'markdown - back
up with rsync or git push to a remote', docs/design-decisions.md says 'No
remote/cloud sync (use git remote on the wiki dir)', and both
docs/airgapped-install.md and SECURITY.md defer the channel security to the
operator ('Remote sync security'). But the recipe itself is nowhere. A
homelab or laptop install has no built-in remote-push cadence, and building
one from scratch takes 100+ lines of bash plus systemd units plus a
gitignore that catches derived state and secrets.

Fill the gap with a docs-only addition:

- New docs/backup.md walks through what to include (wiki/, raw/, config.toml
  minus secrets) vs exclude (db/ derived from wiki via reindex, models/
  redownloadable, logs/, .serve.lock), the rsync + git push + tarball flow,
  the systemd --user timer schedule, restore, and the SECURITY.md-aligned
  posture (private repo, least-privilege push credential, secret exclusion,
  encryption at rest is out of scope for ai-memory).
- A worked example under docs/examples/backup/ following the precedent set
  by docs/examples/jev-reranker-adapter/ and docs/examples/auto-improve-eval/:
  the snapshot script (configurable through six env vars), a systemd --user
  .service oneshot, a daily .timer, a .gitignore for the mirror repo, and
  a README with the install-and-enable steps plus non-systemd equivalents
  for macOS launchd, Windows Task Scheduler via WSL, and Docker sidecar.
- One-line pointers from docs/deploy.md#backups (right after the tarball
  routine) and docs/airgapped-install.md (extending the existing 'git
  remote sync' bullet).
- A row in the README docs table between lifecycle-ops.md and
  llm-providers.md, positioned as a companion to lifecycle-ops.md.

The on-box "ai-memory backup --to TARBALL" command is unchanged. This is
docs-only; no core CLI subcommand for remote push is proposed here (the
issue leaves that decision to the maintainer).

Refs #950.

Co-Authored-By: Claude <noreply@anthropic.com>

2026-09-28 02:19:43 -03:00

3.3 KiB

Raw Blame History

Remote git backup example

Sample scripts + unit files that push an ai-memory install to a remote git repository on a daily cadence, keeping a tarball on a second location for the SQLite index and models cache that the mirror repo deliberately excludes.

See docs/backup.md for the walkthrough. The pieces in this directory are:

ai-memory-snapshot.sh — the rsync + git push + tarball loop. Configurable through six environment variables (REPO_DIR, DATA_SRC, CFG_SRC, TARBALL_DIR, LOG_DIR, SECRET_EXCLUDES) with sensible defaults for a single-user Linux/WSL/macOS install.
ai-memory-backup.service — a systemd --user oneshot that runs the script. %h expands to the user's home directory.
ai-memory-backup.timer — a daily user timer with a small randomised delay and Persistent=true so the missed run after a reboot still fires.
.gitignore — the exclusion list to drop into the root of the mirror repository. Belt-and-braces to the rsync/tar exclude lists in the script itself.

Quickstart

# 1. Create a private repository on your git host (e.g. github.com), then:
mkdir -p ~/ai-memory-backup
cd ~/ai-memory-backup
git init
git remote add origin git@github.com:<you>/ai-memory-backup.git
cp .../docs/examples/backup/.gitignore .
git add .gitignore
git commit -m "initial: ignore secrets, DB, models, logs"
git branch -M main
# push once so `snapshot.sh` has a remote to push to
git push -u origin main

# 2. Drop the snapshot script somewhere on $PATH.
install -Dm755 \
    .../docs/examples/backup/ai-memory-snapshot.sh \
    ~/.local/bin/ai-memory-snapshot.sh

# 3. Install the unit files.
install -Dm644 \
    .../docs/examples/backup/ai-memory-backup.service \
    ~/.config/systemd/user/ai-memory-backup.service
install -Dm644 \
    .../docs/examples/backup/ai-memory-backup.timer \
    ~/.config/systemd/user/ai-memory-backup.timer

# 4. Enable + start.
systemctl --user daemon-reload
systemctl --user enable --now ai-memory-backup.timer

# 5. Trigger one snapshot to confirm the plumbing works.
systemctl --user start ai-memory-backup.service
journalctl --user -u ai-memory-backup.service --since '5 minutes ago'

Non-systemd equivalents

The script is a plain bash program; anything that runs a shell command on a schedule can drive it:

macOS launchd: wrap ai-memory-snapshot.sh in a .plist under ~/Library/LaunchAgents/ with a StartCalendarInterval block.
Windows Task Scheduler: run the script inside WSL via wsl -e bash -lc 'ai-memory-snapshot.sh' on a daily trigger. On native Windows use the PowerShell equivalent of the rsync + git add/commit/push + tar sequence.
Docker sidecar: a small cron container mounted at the ai-memory data volume, running the same script.

Security note

The remote is your own channel, not ai-memory's. Follow the existing SECURITY.md guidance ("Remote sync security"): use a private repository, a fine-grained token scoped to that one repo (or an SSH deploy key), and rotate credentials the same way you rotate any other long-lived push credential. The script never commits files matched by SECRET_EXCLUDES (default: *.env, auth.json, .secrets); the mirror repo's .gitignore catches anything the rsync exclude missed.

3.3 KiB Raw Blame History

Remote git backup example

Quickstart

Non-systemd equivalents

Security note

3.3 KiB

Raw Blame History