> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Synap

> Persistent, cross-session memory for Pipecat voice agents — context injection and conversation recording

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="maximem-ai" maintainerUrl="https://github.com/maximem-ai" repo="https://github.com/maximem-ai/maximem_synap_sdk" />

## Overview

The `synap-pipecat` integration connects [Synap](https://www.maximem.ai/synap),
Maximem AI's long-term memory layer, to Pipecat voice pipelines. It ships two
`FrameProcessor` classes: `SynapMemoryProcessor` injects relevant user memory
into the shared `LLMContext` before the LLM replies, and `SynapRecorder`
captures each user and assistant turn back to Synap so memory persists across
sessions. A `SynapShortTermProcessor` is also provided for injecting short-term
conversation context.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/maximem-ai/maximem_synap_sdk">
    Source code, examples, and issues for the Synap SDK and its Pipecat
    integration (under `packages/integrations/synap-pipecat`)
  </Card>

  <Card title="Documentation" icon="book" href="https://www.maximem.ai/docs">
    Synap documentation from Maximem AI
  </Card>

  <Card title="Website" icon="globe" href="https://www.maximem.ai/synap">
    Learn more about Synap and request an API key
  </Card>

  <Card title="Dashboard" icon="key" href="https://synap.maximem.ai">
    Manage your Synap account and API keys
  </Card>
</CardGroup>

## Installation

This is a community-maintained package distributed separately from `pipecat-ai`:

```bash theme={null}
pip install maximem-synap-pipecat
```

Requires `pipecat-ai>=0.0.80` and `maximem-synap>=0.2.0`.

## Prerequisites

### Synap Account Setup

Before using the Synap integration, you need:

1. **Synap Account / API Key**: Get one at
   [maximem.ai/synap](https://www.maximem.ai/synap)
2. A configured `MaximemSynapSDK` instance, created with your API key:
   `MaximemSynapSDK(api_key="sk-...")`

## Configuration

### `SynapMemoryProcessor`

Inserted **before** the user context aggregator. On each `TranscriptionFrame`,
fetches user-scoped context from Synap and appends it as a system message to the
shared `LLMContext`.

<ParamField path="sdk" type="MaximemSynapSDK" required>
  A configured `MaximemSynapSDK` instance.
</ParamField>

<ParamField path="user_id" type="str" required>
  Required — Synap memory is user-scoped.
</ParamField>

<ParamField path="customer_id" type="str" default="&#x22;&#x22;">
  Optional customer/org scope. An empty string means customer-less.
</ParamField>

<ParamField path="context" type="LLMContext" default="None">
  Shared `LLMContext` used by the user/assistant aggregators. When `None`, the
  processor is inert (no injection) but still passes frames through.
</ParamField>

<ParamField path="mode" type="str" default="&#x22;accurate&#x22;">
  Synap fetch mode (`"accurate"` or `"fast"`).
</ParamField>

<ParamField path="max_results" type="int" default="10">
  Cap on `sdk.fetch` results per turn.
</ParamField>

<ParamField path="include_conversation_context" type="bool" default="False">
  Whether to request Synap's recent conversation block alongside the semantic
  memory.
</ParamField>

### `SynapRecorder`

Inserted **after** the assistant context aggregator. Buffers the latest user
transcription and the streamed assistant response, then records both turns via
`sdk.conversation.record_message` on `LLMFullResponseEndFrame`.

<ParamField path="sdk" type="MaximemSynapSDK" required>
  A configured `MaximemSynapSDK` instance.
</ParamField>

<ParamField path="user_id" type="str" required>
  Required — Synap conversations are user-scoped.
</ParamField>

<ParamField path="customer_id" type="str" default="&#x22;&#x22;">
  Optional customer/org scope. An empty string means customer-less.
</ParamField>

<ParamField path="conversation_id" type="str" default="None">
  Stable id for this call. Auto-generated per processor lifetime when absent.
</ParamField>

<Note>
  A `SynapShortTermProcessor` is also exported for injecting short-term
  conversation context. See the [source
  repository](https://github.com/maximem-ai/maximem_synap_sdk) for its full
  configuration.
</Note>

## Usage

```python theme={null}
from pipecat.pipeline.pipeline import Pipeline
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import (
    LLMUserAggregator,
    LLMAssistantAggregator,
)
from maximem_synap import MaximemSynapSDK
from synap_pipecat import SynapMemoryProcessor, SynapRecorder

sdk = MaximemSynapSDK(api_key="sk-...")
context = LLMContext(
    messages=[{"role": "system", "content": "You are a helpful assistant."}]
)

user_agg = LLMUserAggregator(context=context)
asst_agg = LLMAssistantAggregator(context=context)

pipeline = Pipeline([
    transport.input(),
    stt,
    SynapMemoryProcessor(sdk, user_id="alice", customer_id="acme", context=context),
    user_agg,
    llm,
    tts,
    transport.output(),
    asst_agg,
    SynapRecorder(sdk, user_id="alice", customer_id="acme"),
])
```

<Note>
  Reads degrade gracefully — if a Synap fetch fails, the frame continues
  downstream with no context injected so a Synap blip never breaks a live call.
  Write failures surface as a `SynapIntegrationError` pushed upstream as an
  `ErrorFrame`.
</Note>

## Compatibility

The integration requires `pipecat-ai>=0.0.80`. Check the [source
repository](https://github.com/maximem-ai/maximem_synap_sdk) for the latest
tested version and changelog.