Skip to main content
REST One HTTPS request, unless the answer comes from this process: from the SDK’s own copy in short-term authoritative mode, or, in Python, from the 5-minute response cache. When the history search needs earlier turns this process does not hold, the SDK also downloads them in the background, up to 500 per page and at most once a minute per conversation. Works in any Python or Node 20+ process, including serverless functions. Returns a single formatted_context string that stitches together the compacted history with any messages that arrived after the last compaction cutoff. Drop the result straight into your prompt. No further assembly required. If no compaction has run yet, every recorded message comes back as a recent message, so this method is useful from the very first turn.

Parameters

str
required
The conversation to assemble context for. Must be a valid UUID registered via record_message. An id this instance has not recorded raises AuthenticationError (HTTP 403).
str
default:"structured"
Formatting style for the compacted portion:
  • "structured": labelled sections (facts, decisions, preferences, current state)
  • "narrative": prose summary
  • "bullet_points": bulleted list
Has no effect on compactions made by the current pipeline, which come back as one pre-rendered block. It applies only to older compactions stored without one. Any other value is refused.
bool
default:"True"
After a compaction, the summary can leave out a detail an earlier turn had. With this on, the SDK searches the earlier turns for the ones that best match query, and adds up to six of them at the end of formatted_context, quoted word for word but cut to about 60 words each, each with the turn just before it (up to 40 words) for context. The search runs on your machine. If this process holds fewer turns than the conversation, for example after a restart, the SDK downloads the missing ones in the background, so the first call afterwards searches only what is already local. Before the first compaction it changes nothing, because every turn is still in the prompt. The search matches words; with the local search model installed it also matches meaning. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later, as search_history (or searchHistory).
str
What to search the earlier turns for. Defaults to the latest user message. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later.

Returns

A ContextForPromptResponse ready for prompt injection.
str | None
The combined compacted + recent context, formatted per style. Inject directly into your LLM prompt.
bool
Whether usable context (compacted or recent) was found.
bool
True when the compaction is more than 15 minutes old. Always false when the SDK builds the answer from its own copy of the conversation.
float | None
Compression ratio of the compacted portion.
float | None
Quality validation score of the compacted portion.
int | None
How long ago the compaction completed.
bool
True when the compacted portion was flagged for quality concerns.
List[Dict[str, Any]]
Raw un-compacted messages since the last compaction. Use if you want to format them yourself.
int
Number of un-compacted messages included.
int
Number of messages covered by the compacted portion.
int
Total messages in the conversation.
List[HistoryExcerpt]
The earlier turns the history search added, each with its position, role and text. Empty when nothing matched or no compaction exists yet.
str | None
Those excerpts as the text block appended to formatted_context, in case you place them yourself.

Example

Raises

  • InvalidInputError: when style is not "structured", "narrative" or "bullet_points" (Python 0.5.15 and JavaScript 0.5.14 and later).
  • InvalidInputError: when conversation_id is empty (Python 0.5.15 and later; all JavaScript versions).
  • InvalidConversationIdError, a subclass of InvalidInputError: when conversation_id is not a valid UUID.
  • AuthenticationError: when the conversation does not exist or belongs to another instance (HTTP 403, “Conversation not found or access denied”). Python 0.5.15 and later; earlier Python raised SynapTransientError.
  • AuthenticationError with the message “SDK not initialized”: when called before await sdk.initialize() (Python). JavaScript resolves the client’s identity on the first call instead.
  • AuthenticationError: when the API key is invalid or revoked. A missing key fails earlier, when the client is created (JavaScript) or initialized (Python).
  • NetworkTimeoutError: the SDK could not reach Synap (a timeout, or a refused or dropped connection) after its retries. ConnectionError is the same class in both SDKs (JavaScript 0.5.13 and later).

See also