conversation.context.get_compacted

await sdk.conversation.context.get_compacted(
    conversation_id: str,
    version: Optional[int] = None,
    format: str = "structured",
) -> Optional[CompactionResponse]

Fetches the most recent compacted summary for a conversation. Local SDK cache is checked first (5 minute TTL); on miss the SDK fetches from Synap and caches the result. Returns None if no compacted summary exists yet. Call compact first in that case. When a specific version is requested the local cache is bypassed and the value is fetched fresh from Synap.

Parameters

str

required

The conversation whose compacted summary you want to read. Must be a valid UUID registered via record_message.

int

Specific compaction version. Defaults to the latest. When supplied, the SDK always fetches from the cloud and skips the local cache.

str

default:"structured"

Output format:

"structured": structured fields (facts, decisions, preferences, current_state)
"narrative": prose summary
"injection": preformatted for direct prompt injection

Returns

A CompactionResponse if a compacted summary exists, otherwise None.

str

The formatted compacted context.

int

Token count of the original conversation.

int

Token count after compaction.

float

Compaction ratio (compacted / original).

CompactionLevel

Strategy actually applied (e.g., adaptive, balanced).

str | None

Identifier of the compaction run that produced this summary.

str | None

Strategy used for this compaction.

float | None

Quality validation score, when available.

bool | None

Whether the validation check passed.

List[str]

Extracted facts (structured format).

List[str]

Extracted decisions (structured format).

List[str]

Extracted preferences (structured format).

Dict[str, Any] | None

Snapshot of current conversation state (structured format).

str | None

Optional warning when validation flagged a concern.

ResponseMetadata

Correlation id, source (cache or cloud), TTL, and retrieval timestamp.

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())

compacted = await sdk.conversation.context.get_compacted(
    conversation_id=conversation_id,
    format="structured",
)

if compacted is None:
    print("No compaction yet. Trigger one with sdk.conversation.context.compact()")
else:
    print(f"Compressed {compacted.original_token_count} -> {compacted.compacted_token_count} tokens")
    for fact in compacted.facts:
        print("-", fact)

Raises

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

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation