Activity & Audit Trail

Browse, export, and append chronological activity entries for observability and compliance.

MuBit tracks all memory operations as a chronological activity trail. Use it for observability, debugging, compliance audit, and manual trace annotation.

Activity is distinct from semantic retrieval (recall / query). It provides exact chronological ordering — what happened and when — rather than ranked relevance.

Browse activity

List recent activity entries for a run with optional type and agent filters.

POST /v2/control/activity returns entries sorted newest-first (sort defaults to "desc"). limit defaults to 100 and is clamped to 500. Each entry uses the proto field names — note entry_type and created_at (not type/timestamp).

curl -sS http://localhost:3000/v2/control/activity \
  -H "Authorization: Bearer $MUBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "support:acme:ticket-42",
    "limit": 50,
    "entry_types": ["fact", "lesson"]
  }'

{
  "entries": [
    {
      "id": "evt_01H...",
      "run_id": "support:acme:ticket-42",
      "agent_id": "support-agent",
      "entry_type": "fact",
      "content": "Customer on enterprise plan since 2023",
      "created_at": "2026-06-03T14:02:11Z"
    }
  ],
  "next_page_token": "",
  "total_visible": 1
}

Export activity

Export the full activity trail for offline analysis or compliance archival. The request takes the same filters as the browse call (run_id, user_id, agent_id, entry_types, created_after, created_before, sort) — there is no format request field. The response always returns JSONL, with the format string and serialized entries in the response's format and content fields.

curl -sS http://localhost:3000/v2/control/activity/export \
  -H "Authorization: Bearer $MUBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "run_id": "support:acme:ticket-42" }'

{
  "format": "jsonl",
  "content": "{\"id\":\"evt_01H...\",\"entry_type\":\"fact\",...}\n",
  "entry_count": 1
}

Append activity

Manually append an activity trace — useful for logging external observations, human annotations, or system events that aren't captured automatically. Each request appends a single activity record (not a list). The record carries type and payload (required) plus optional tool_name, input_ref, output_ref, ts, and agent_id. Issue one request per record.

curl -sS http://localhost:3000/v2/control/activities/append \
  -H "Authorization: Bearer $MUBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "support:acme:ticket-42",
    "agent_id": "support-agent",
    "activity": {
      "type": "observation",
      "payload": "Customer escalated via phone"
    }
  }'

Activity vs. semantic query

Use activity for "what happened" questions. Use query/recall for "what's relevant" questions.

API reference

See Control HTTP reference and Control gRPC reference for full request/response schemas.

Next steps

• See SDK methods for the full method catalog.
• See Control HTTP reference for request/response field details.