conversation.context.compact

await sdk.conversation.context.compact(
    conversation_id: str,
    strategy: Optional[str] = None,
    compaction_level: Optional[str] = None,
    target_tokens: Optional[int] = None,
    force: bool = False,
) -> CompactionTriggerResponse

Kicks off compaction for a conversation. Compaction runs asynchronously. This call returns a handle with a compaction_id and an in_progress status. Use get_compaction_status to poll for completion, then get_compacted to retrieve the resulting summary. If a previous compacted summary already exists, it is returned on the trigger response as previous_context so you have something usable while the new compaction runs.

Parameters

str

required

The conversation to compact. Must be a valid UUID registered via record_message.

str

Override the compaction strategy. One of:

"aggressive": maximum compression, shortest output
"balanced": middle-ground compression
"conservative": preserve more detail
"adaptive": let Synap pick based on conversation shape

str

Backward-compatible alias for strategy. Prefer strategy in new code.

int

Override the target token budget for the compacted output.

bool

default:"False"

Compact even if the conversation has not crossed the automatic threshold.

Returns

A CompactionTriggerResponse describing the in-flight job.

str

Identifier for this compaction run.

str

Echo of the supplied conversation id.

str

Initial status, typically "in_progress".

str

How compaction was triggered (e.g., "manual_api").

datetime

When the run started.

int

Rough ETA in seconds.

Dict[str, Any] | None

Previously compacted context, if any. Usable while the new run finishes.

int | None

Age of previous_context in seconds.

str | None

Identifier of the previous compaction run.

Example

import uuid
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(api_key="synap_your_key_here")
await sdk.initialize()

# conversation_id must be a valid UUID; reuse the conversation's id
conversation_id = str(uuid.uuid4())

job = await sdk.conversation.context.compact(
    conversation_id=conversation_id,
    strategy="balanced",
    target_tokens=800,
)

print(f"Compaction {job.compaction_id} started (status: {job.status})")
if job.previous_context:
    print("Previous compacted context still usable while new run completes.")

Raises

AuthenticationError: when the API key is missing or invalid.
NetworkError: when the SDK cannot reach Synap.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation