OmniMemora

API Reference

This page documents the current minimal Agent Memory API surface that is already wired into the live demo. It is intentionally small: one unified query endpoint, one request-level meter endpoint, and two tenant-level usage endpoints.

OmniMemora API is designed for production agents with high token cost and long memory chains.
4documented endpoints
Livebacked by adapter :8000
Meteredrequest + tenant usage views
Estimatetoken savings are heuristic, not billing-grade
POST
/memory/query

Unified recall entrypoint for OmniMemora. Selects memories, builds packed context, and emits a request-scoped meter reference for the current query.

real

Request Shape

  • tenant, user, agent, query
  • context.client may identify caller channel
  • options.max_local_cards and options.enable_packing are optional

Response Shape

  • request_id
  • selected_memories[]
  • packed_context
  • memory_tokens_injected
  • tokens_saved_estimate, savings_ratio
  • meter_artifact.$ref
{
  "tenant": "18790-account",
  "user": "18790-user",
  "agent": "supervisor",
  "query": "V2 smoke memory ov-v2-smoke-92329c5d",
  "context": { "client": "openclaw" },
  "options": { "max_local_cards": 4, "enable_packing": true }
}
GET
/requests/{id}/meter

Fetches the full per-request Token Savings Meter artifact for one OmniMemora query.

estimate

Request Shape

  • Path parameter: request_id
  • No request body

Response Shape

  • Identity: tenant, user, agent
  • Token estimates: baseline_tokens_estimate, actual_tokens_estimate, saved_tokens_estimate
  • Explanation fields: local cards, remote skipped, packing, dedup
{
  "request_id": "req-50155a03",
  "tenant": "18790-account",
  "baseline_tokens_estimate": 418,
  "actual_tokens_estimate": 72,
  "saved_tokens_estimate": 346,
  "savings_ratio": 0.828
}
GET
/usage/token-savings

Returns aggregated savings totals for a tenant, including recent requests and by-agent breakdown.

estimate

Request Shape

  • Required query: tenant
  • Optional: agent, start_time, end_time

Response Shape

  • total_requests
  • baseline_tokens_total, actual_tokens_total, saved_tokens_total
  • average_savings_ratio
  • by_agent[] and recent_requests[]
GET
/usage/token-savings/trend

Returns a lightweight tenant trend series for the last N days. Used by the current OmniMemora demo chart.

real

Request Shape

  • Required query: tenant
  • Optional: agent, days

Response Shape

  • tenant, days
  • trend[] with date, requests, saved_tokens, savings_ratio
Request commercial API access or a guided demo if you want this surface on your own agent workloads.
Request API Access
Status semantics used on this page:
real = endpoint is live on the current adapter and has been smoke-tested.
estimate = endpoint is live, but the token math is intentionally heuristic and should not yet be treated as billing-grade metering.