Skip to content

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.md
index 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.md
new file mode 100644
index 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.