---
title: "Compact User Context"
method: POST
path: "/api/admin/users/{user_id}/compact-now"
tags: ["admin"]
---

# Compact User Context

`POST /api/admin/users/{user_id}/compact-now`

Synchronously compact a user's currently-visible conversation context.

Use this when a bug or model error has poisoned a user's in-context
conversation history (e.g. the agent confidently asserted a wrong
fact about its own capabilities) and you want to reset the LLM-facing
context without dropping durable user-supplied facts. The OSS
``admin_compact_visible_messages`` helper extracts facts into
MEMORY.md / USER.md / SOUL.md before advancing the trim watermark,
so the next turn starts from a clean slate plus the rewritten memory.

``keep_recent`` preserves the last N visible turns so the user's
pending request is not lost when an admin clears stale context
mid-conversation. ``hint`` is prepended to the compaction LLM's
``<conversation>`` block as ``[admin note: ...]`` to bias how the
LLM reads the messages, which is useful when the exact failure mode
is known (e.g. "ignore prior agent claims about being read-only").

Audit-logged via ``AdminAction.COMPACT_USER_CONTEXT``; the resulting
``compaction_events`` row is also linked from ``ctx.detail`` so a
forensic query can join admin action to the compaction outcome.

## Path parameters

- `user_id` string, required

## Request body

- CompactUserContextRequest — Body for ``POST /admin/users/{user_id}/compact-now``. Both fields are optional: a bare ``{}`` runs the default "compact everything visible, no LLM steering" behavior.
  - `keep_recent` integer — Preserve the last N visible messages from compaction so the agent retains immediate context (e.g. a pending user request).
  - `hint` string, nullable — Optional steering note prepended inside the compaction LLM's <conversation> block as `[admin note: ...]`. Use to bias how the LLM reads the conversation, e.g. 'ignore prior agent self-claims about AppFolio capabilities'.

## Response `200`

Successful Response

- CompactUserContextResponse — Outcome of an admin-triggered context compaction. ``event_id`` is the row this call wrote, populated only when the call did real work. ``previous_event_id`` is populated only on no-op returns and points at the most recent prior compaction event for the user (if any), so admin tooling can tell apart "you already did this seconds ago" from "there was never anything to do".
  - `compacted_message_count` integer, required
  - `new_watermark` integer, nullable, required
  - `memory_updated` boolean, required
  - `event_id` integer, nullable, required
  - `previous_event_id` integer, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mozilla-ai/apis/clawbolt.md) · [All operations](https://skmtc.net/mozilla-ai/apis/clawbolt/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mozilla-ai/clawbolt/revisions/0e52fe5f8d33/schema)