ambrogio-memory — the verbs

Parent: topics/ambrogio-memory-contract. Entity: entities/ambrogio-memory. The machine-readable copy is GET /api/v1 (the index) and GET /api/v1/skill (the contract an agent reads).

Base: http://192.168.1.206:7810. Reads are open on the private network; no token is asked.

Reads

verbparametersanswers
GET /healthz—ok, uptime, commit
GET /api/v1—the index: 33 verbs, parameters, one line each
GET /api/v1/version—commit, counters, the gate, the open jobs
GET /api/v1/contextbudget_bytes, sincethe boot bundle; included, omitted, truncated, words, rules_over_budget
GET /api/v1/state—the state, section by section
GET /api/v1/debtsstatus, qthe register, filtered
GET /api/v1/debts/{id}—one debt
GET /api/v1/logsince, cursor, limit, kind, scopethe log from a cursor (cursor is the alias of since)
GET /api/v1/summary—the last closed cycle’s account
GET /api/v1/archivessummary, since, limitthe closed cycles, newest first, with a cursor
GET /api/v1/archives/{id}—one cycle and its four snapshots
GET /api/v1/documentskind, tag, since, limitreports and notes, newest first, with a cursor
GET /api/v1/documents/{slug}—one document in full
GET /api/v1/rules · /rules/{name}—the rules, always-apply first
GET /api/v1/searchq, limitFTS5 over log, debts, documents, rules
GET /api/v1/skill—the client contract
GET /api/v1/crons—the appointments and their last result

Writes

verbbodynotes
POST /api/v1/logactor, kind, title, body_md, tags[], scope, client_entry_idkind is work, decision, problem, error, note; over 600 words → 409 naming the ceiling; a repeated client_entry_id returns the entry already written with duplicate: true
POST /api/v1/state/changesactor, changes[]append, remove, replace (one section), create, rename; a non-match is refused with the current text; the accepted ones stay applied
POST /api/v1/debtsactor, area, debt, impact, next_actionthe id is assigned by the service; never invent one
POST /api/v1/debts/{id}/statusactor, status, next_actionopen, in_progress, deferred; a closed debt is not reopened
POST /api/v1/debts/{id}/closeactor, resolution, closedthe resolution and the date are required
POST /api/v1/documentactor, kind, title, body_md, tags[]kind is report or note; written once
POST /api/v1/rulesname, title, body_md, always_apply
PUT /api/v1/rules/{name}body_md, title, always_applya new version
DELETE /api/v1/rules/{name}—the deletion is logged
POST /api/v1/compact—queues the act; it never runs inline
POST /api/v1/render—writes the export into the memory directory
POST /api/v1/crons/{name}/run—runs an appointment now
POST /api/v1/crons/{name}/enableenabled
POST /api/v1/crons/{name}/everyevery_msat least 60,000
PUT /api/v1/settings/{name}valuecounts are checked: chronicle_gate_words, bundle_budget_bytes, bundle_debts_max, max_log_words, summary_max_words, backup_keep

Refusals that are the contract

  • unknown query parameter → 400 naming the ones the verb accepts (a silently ignored ?after=35 is a client that believes it paged);
  • a body over the ceiling → 409 with the count and the ceiling;
  • a state change that does not match → 200 with refused[], each naming the reason and the current text;
  • closing a debt without a resolution → 400; closing twice → 409;
  • on a -read-only instance, a write → 503 with a sentence.

Operational facts

  • The service runs as a systemd user unit; journalctl --user -u ambrogio-memory shows start/stop, while the service’s own log is data/logs/memory.log (rotating).
  • The cage is a Landlock allow-list applied at boot: system directories read-only, its data directory and the repository that holds the backup writable, port 7810 bound, outbound 443 for the model, and the resolver’s real directory.
  • Two 0600 files hold the only secrets: data/opencode.key (the model) and data/github.token (the backup push). Both come from gopass.

See Also