Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: lifecycle-ops.md + README link — safety matrix for state-touching commands
AkitaOnRails2a25aa3f4019
diff --git a/README.md b/README.mdindex 46aae6af..6a9357a0 100644--- a/README.md+++ b/README.md@@ -587,6 +587,7 @@ data-flow diagram + crate breakdown + cross-cutting invariants.| [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine (homelab/LAN) walkthrough. Read after the Quick start if your setup doesn't match the happy path. || [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP config snippets (Cursor, Claude Desktop, Gemini CLI, OpenClaw, pi). || [`docs/deploy.md`](docs/deploy.md) | Homelab deploy: bin/deploy, bearer-token auth, TLS via cloudflared. |+| [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) | **Read before running purge / rename / backup / restore / reset.** Safety matrix for the state-touching commands, per-project disk layout (how isolation actually works), and operator workflows for "fresh start", "snapshot before risky op", "drop one project". || [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. || [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. || Research docs under `docs/` | Karpathy LLM Wiki notes, agentmemory / basic-memory / cognee deep-dives, lessons-learned from upstream issues. |diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdnew file mode 100644index 00000000..265caade--- /dev/null+++ b/docs/lifecycle-ops.md@@ -0,0 +1,268 @@+# Lifecycle operations++Reference for the destructive / state-touching ai-memory commands.+Read this before running anything that mutates wiki + db, especially+on a homelab box where mistakes are harder to undo.++## TL;DR — safety matrix++| Command | Safe with server **running**? | Wipes data? | Reversible? | Notes |+|---|---|---|---|---|+| `purge-project --confirm` | ✅ yes | the one project's data | no | Atomic `rm -rf <project_root>` on the namespaced disk path; sibling projects untouched. |+| `rename-project --from --to` | ✅ yes | no | yes (rename back) | Column-only update on `projects.name`. The on-disk dir is keyed by `project_id` (UUID), so the rename never moves a file. |+| `backup --output-path` | ✅ yes | no | n/a | Streams a gzipped tarball from the server's online `sqlite3 .backup` plus the wiki tree. Safe alongside the live writer. |+| `restore --from <tarball>` | ❌ **stop the server first** | overwrites the data dir | no (without prior backup) | Refuses if any sibling `ai-memory` process is alive (sysinfo guard). |+| `reset --confirm` | ❌ **stop the server first** | yes, all data | no | Refuses if any sibling `ai-memory` process is alive (sysinfo guard). |++All five commands route through the HTTP admin API except `reset` and+`restore`, which are direct-disk operations that fundamentally cannot+run while another process holds the SQLite WAL writer. See [CLAUDE.md+§16](../CLAUDE.md) for the invariant.++## What "project isolation" means here++Every project's data lives under an isolated, UUID-keyed root on disk:++```+<wiki_root>/+├── .git/+├── <workspace_id>/+│ └── <project_id>/+│ ├── concepts/+│ ├── decisions/+│ ├── gotchas/+│ ├── sessions/+│ ├── _rules/+│ ├── log.md+│ └── bootstrap.md+└── <other_workspace_id>/+ └── <other_project_id>/+ └── ...+```++The mutable **project name** (the human-readable `distrobox-gaming`+or `.config` you see in `/web/`) never appears in any disk path; the+stable **project_id UUID** does. SQLite's `projects.name` column maps+name → id. Two projects can have the exact same `pages.path` (e.g.+both have `decisions/0001.md`) without colliding on disk — the+namespaced layout guarantees structural isolation.++The git history is rooted at `<wiki_root>` (one repo, all projects+as subtrees). A `git log` from inside the wiki dir shows changes+across every project; per-project diffs are also possible via+`git log -- <workspace_id>/<project_id>/`.++## Command-by-command++### `purge-project`++```bash+ai-memory purge-project --workspace default --project my-project --confirm+```++What happens, in order:++1. Server looks up `(workspace_id, project_id)` by name. Returns 404+ if either is missing.+2. Counts rows that will cascade (`pages`, `sessions`,+ `observations`, `handoffs`, `page_embeddings`).+3. Single `DELETE FROM projects WHERE id = ?` — the V01 + V05+ `ON DELETE CASCADE` foreign keys propagate to every dependent+ table in one transaction.+4. `std::fs::remove_dir_all(<wiki_root>/<workspace_id>/<project_id>)`+ wipes the on-disk project root.+5. Returns a summary: `{label, pages_deleted, sessions_deleted, …,+ files_deleted: [<project_root>], files_failed: [...]}`.++Failure modes:++- **Workspace or project name not found** → 404, no mutation.+- **Confirmation flag omitted** → 400, no mutation.+- **`remove_dir_all` partial failure** (e.g. permissions) → DB+ rows are already gone but `files_failed` is populated. Re-run+ the command with the same args is idempotent; the second call+ returns 404 (project already deleted).++Why this is safe with the server running:++- The DB cascade is one transaction; the writer actor serialises+ it against any other writes.+- The on-disk delete touches only the project's UUID-keyed subdir,+ which no other project shares files with. No race with the+ watcher even mid-write — at worst the watcher emits delete+ events for files we just removed, which it ignores (no DB row+ to reindex).++### `rename-project`++```bash+ai-memory rename-project --workspace default --from old-name --to new-name+```++What happens:++1. Look up `(workspace_id, project_id)` by current name. 404 on+ miss.+2. Validate the new name: non-empty, no `/`, no leading/trailing+ whitespace. 422 on bad input.+3. `UPDATE projects SET name = ? WHERE id = ?`. UNIQUE-violation on+ the `(workspace_id, name)` index → 422 with "name taken".+4. Return `{label, from, to, pages}`.++Zero files move on disk because the disk path is keyed by+`project_id`, not name. The web UI URL `/web/w/<ws>/<proj-name>/…`+just resolves to the same `project_id` after the column update.++Failure modes:++- **`to` name already exists in this workspace** → 422.+- **`to` invalid (empty, slash, whitespace)** → 422.+- **Source `from` not found** → 404.++### `backup`++```bash+ai-memory backup --output-path /tmp/ai-memory-backup.tar.gz+```++What happens on the server:++1. SQLite online-backup API copies the live WAL DB to a temp file —+ guaranteed consistent snapshot without stopping the writer.+2. Server tar-gzips the snapshot + the wiki tree + `config.toml`.+3. Response body IS the gzipped tarball+ (`Content-Type: application/gzip`).++CLI writes the response body to `--output-path`. For a homelab user+this is the standard "snapshot before doing something dangerous"+move — `ai-memory backup` first, then proceed.++Restoring a backup follows the inverse:++```bash+# Stop the server first.+docker compose -f ~/deploy/ai-memory/docker-compose.yml down+# Restore (sysinfo refuses if the container is still running).+ai-memory restore --from /tmp/ai-memory-backup.tar.gz --data-dir /var/opt/docker/utils/ai-memory/data --confirm+# Start back up.+docker compose -f ~/deploy/ai-memory/docker-compose.yml up -d+```++The `--data-dir` flag points the CLI at the host-side path of the+docker volume (since `restore` runs directly on disk, not via the+HTTP admin API).++### `restore`++```bash+ai-memory restore --from <tarball> --data-dir <path> --confirm+```++Direct-disk operation. Refuses if any other `ai-memory` process is+alive (uses `sysinfo` to scan the process table).++Order of operations:++1. Check the data dir is empty (or the user passed `--force`).+2. Extract the tarball into the data dir.+3. Restore the SQLite snapshot in place.+4. Print a one-line summary.++Failure modes:++- **Server still running** → exits with "another ai-memory process is+ alive (pid X); stop it before restoring" — same wording as `reset`.+- **`--confirm` omitted** → exits with usage hint.+- **Data dir not empty + no `--force`** → exits with "data dir not+ empty; pass `--force` to overwrite".++### `reset`++```bash+ai-memory reset --confirm+```++Direct-disk operation. Refuses if any sibling `ai-memory` process is+alive. Removes the contents of `wiki/`, `db/`, and `raw/` under the+configured data dir. `config.toml` is preserved.++Identical sysinfo guard to `restore`. The use case is "wipe and start+over" — typically when changing major version with a breaking+migration, or when bootstrapping a new install on top of an old+data dir.++For a docker deploy where the data lives in a host-path bind mount,+you can also just `rm -rf <host-path>/*` after stopping the+container — but `ai-memory reset` is the cross-platform path that+works whether the data dir is local, bind-mounted, or in a named+volume.++## Operator workflows++### "Fresh start" (wipe everything)++For a docker / bind-mount deploy where data lives on the host:++```bash+ssh homelab+cd ~/deploy/ai-memory+docker compose down+sudo rm -rf /var/opt/docker/utils/ai-memory/data/*+docker compose up -d+```++Or via the CLI from any machine (slower but portable):++```bash+docker stop ai-memory # so sysinfo guard passes+ai-memory reset --confirm # against the same data dir+docker start ai-memory+```++### "Snapshot before risky op"++```bash+ai-memory backup --output-path "/tmp/ai-memory-$(date +%Y%m%d-%H%M).tar.gz"+# … do the risky thing …+# … oh no something broke …+docker compose down+ai-memory restore --from /tmp/ai-memory-2026-05-23-1530.tar.gz --confirm+docker compose up -d+```++### "Drop one experimental project, keep everything else"++```bash+ai-memory purge-project --project experimental --confirm+# Sibling projects (ai-memory, distrobox-gaming, …) untouched.+```++### "Rename a project after `mv ~/Projects/old ~/Projects/new`"++```bash+ai-memory rename-project --from old --to new+# Future sessions in ~/Projects/new will append to the same project+# (the hook router stamps by basename(cwd) = "new"); past+# observations stay under that project too because the project_id+# is stable.+```++## Why this matters: the flat-wiki incident++Before the per-project disk layout (commits up to `e7b9a17`), the+wiki was flat: `wiki/<page-path>` regardless of project. Two+projects with the same `pages.path` shared one file on disk. The+`purge-project` handler then iterated and deleted those files,+clobbering pages owned by the sibling project. The DB rows for the+sibling survived (FK is scoped by `project_id`), but every `/web/`+click returned 404 because the on-disk file was gone.++The shipped band-aid was a `path_still_referenced` check before each+delete. The proper fix landed in `e7b9a17`: per-project disk roots+make path-collision structurally impossible. Both the band-aid and+the underlying class of bug are gone. Lifecycle ops are now safe+by construction.++This is also why `rename-project` is free: the disk path is keyed+by surrogate `project_id`, not the mutable name. Rename touches one+column; nothing moves.