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.mdindex 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 areJSON 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. Toclaim 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 separatelyand account for concurrent updates in a local cache. Endpoint details anderrors 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.