Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(programmatic): map lifecycle operations to the calls that exist (#1165)

AkitaOnRails7e711732d8cb
diff --git a/docs/programmatic-memory.md b/docs/programmatic-memory.md
index 7ddb1c3b..e7bb35ee 100644
--- a/docs/programmatic-memory.md
+++ b/docs/programmatic-memory.md
@@ -66,6 +66,25 @@ Check JSON-RPC `error` and `result.isError` even on HTTP 200. Tool payloads are
JSON encoded inside `result.content[].text`. A page write returns `page_id` and
`path`; a query returns `hits`.
+ai-memory's own tools report a failure as a JSON-RPC `error` with a code and
+message, for example `-32602` for invalid parameters or `-32603` when an
+admission webhook rejects a write. `result.isError` is where MCP lets a tool
+report its own failure, so check it too. A caller using `jq` can branch on both:
+
+```bash
+response=$(mcp <<'JSON'
+{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"memory_read_page","arguments":{"workspace":"demo","project":"app","path":"notes/retries.md"}}}
+JSON
+)
+if jq -e '.error' <<<"$response" >/dev/null; then
+ jq -r '"rpc error \(.error.code): \(.error.message)"' <<<"$response" >&2
+elif jq -e '.result.isError == true' <<<"$response" >/dev/null; then
+ jq -r '.result.content[].text' <<<"$response" >&2
+else
+ jq -r '.result.content[].text | fromjson' <<<"$response"
+fi
+```
+
Writes and handoff creation may create the explicit scope if it is missing.
Reads fail closed on missing or partial scope. A handoff is claimed once. To
claim a particular one, pass the exact `handoff_id` from `memory_handoff_begin`
@@ -97,3 +116,39 @@ The incremental path is not cached and omits expired and superseded pages.
It has no deletion feed or snapshot across calls. Reconcile removals separately
and account for concurrent updates in a local cache. Endpoint details and
errors are in [frontend-api.md](frontend-api.md).
+
+## Lifecycle from code
+
+Deleting, restoring and purging memory goes through two surfaces. A page
+delete is an MCP tool. Restore and purge are admin HTTP routes. Every
+`/admin/*` route is root-only once the deployment has a DB user or
+trusted-proxy identities (see [users.md](users.md)); until then they accept
+any caller the server's auth lets in.
+
+| Operation | Call | Notes |
+|---|---|---|
+| Delete a page (there is no separate archive) | MCP `memory_delete_page` with `path` (plus `workspace` and `project`) | Checkpoints the wiki in git first, then removes the file and every indexed version of the page. Returns `{path, deleted, pre_checkpoint, checkpoint}`. Idempotent. |
+| Restore a deleted or overwritten page | `POST /admin/restore-page` with `{workspace, project, path, rev}` | `rev` is any git revision that still holds the page: the delete's `pre_checkpoint`, or `<checkpoint>~1` when `pre_checkpoint` is `null` because the tree was already clean. Writes that version back as the latest page and reindexes it. After a delete, only that one version returns. |
+| Find a revision | `GET /admin/checkpoints?limit=N` | Recent checkpoints (up to 100) with `oid` and `summary`. A delete's summary is `memory_delete_page: <path>`. |
+| Purge one session | `POST /admin/purge-session` with `{workspace, project, session_id, confirm}` | Irreversible. Optional `dry_run` and `compact`. |
+| Purge a whole project | `POST /admin/purge-project` with `{workspace, project, confirm}` | Irreversible. Optional `dry_run`, `compact`, and `force` (purge despite a live managed-workstream lease). |
+| Read superseded versions | MCP `memory_query` with `include_superseded=true` | Older versions are labelled `superseded: true`. A delete removes them along with the current version. |
+
+Both purge routes refuse with 400 unless `confirm` is `true`, and `dry_run`
+wins over `confirm`: a body with both set only previews the counts. `confirm`
+is a required field, so a preview sends it as `false`. Once root-only applies,
+`ROOT_TOKEN` below must be the root bearer token; a user API key is refused.
+
+```bash
+curl --silent --show-error --fail-with-body \
+ "${AI_MEMORY_SERVER_URL%/}/admin/purge-session" \
+ -H 'Content-Type: application/json' \
+ -H "Authorization: Bearer ${ROOT_TOKEN}" \
+ -d '{"workspace":"demo","project":"app","session_id":"<session-uuid>","confirm":false,"dry_run":true}'
+```
+
+There is no endpoint that lists deleted pages and no MCP tool that restores
+one. To recover a page, take the revision from the delete response or from
+`/admin/checkpoints`, then call `/admin/restore-page` as root.
+[lifecycle-ops.md](lifecycle-ops.md) covers what each purge deletes, the
+matching CLI commands, and the cross-project side effects.