supermemory-pipecat 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: supermemory-pipecat
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Supermemory integration for Pipecat - memory-enhanced conversational AI pipelines
5
5
  Project-URL: Homepage, https://supermemory.ai
6
6
  Project-URL: Documentation, https://docs.supermemory.ai
@@ -98,7 +98,8 @@ memory = SupermemoryPipecatService(
98
98
  search_limit=10, # Max memories to retrieve
99
99
  search_threshold=0.1, # Similarity threshold
100
100
  mode="full", # "profile", "query", or "full"
101
- inject_mode="auto", # "auto", "system", or "user"
101
+ inject_mode="auto", # "auto", "user", or "system"
102
+ storage_drain_timeout=3.0, # Seconds cleanup waits for pending writes
102
103
  system_prompt="Based on previous conversations, I recall:\n\n",
103
104
  ),
104
105
  )
@@ -106,25 +107,78 @@ memory = SupermemoryPipecatService(
106
107
 
107
108
  ### Memory Modes
108
109
 
109
- | Mode | Static Profile | Dynamic Profile | Search Results |
110
- | ----------- | -------------- | --------------- | -------------- |
111
- | `"profile"` | Yes | Yes | No |
112
- | `"query"` | No | No | Yes |
113
- | `"full"` | Yes | Yes | Yes |
110
+ | Mode | Profile block (system message) | Search block (user message) |
111
+ | ----------- | ------------------------------ | --------------------------- |
112
+ | `"profile"` | Yes | No |
113
+ | `"query"` | No | Yes |
114
+ | `"full"` | Yes | Yes |
115
+
116
+ ### Where memories go
117
+
118
+ - **Profile:** fetched once per conversation, on the first context frame (even
119
+ before the first user message), and appended as a `<user_memories>` block to the
120
+ first system message, or sent as a new leading system message when there is
121
+ none. It is never refreshed, so it stays byte-identical on every later request,
122
+ and it never appears in a user message.
123
+ - **Search results:** each user turn is searched once, and the results are
124
+ appended as a `<user_memories>` block to the user message they were retrieved
125
+ for. Earlier user messages keep the block they first received. Results the
126
+ profile already covers are skipped.
127
+ - **Tool calls:** steps inside a turn reuse that turn's block and never search again.
128
+ - **Turn identity:** a turn is keyed by its text plus the assistant reply before it,
129
+ so a repeated question after a new reply is a new turn with its own search, and
130
+ trimming old history from the front keeps every kept message's block.
131
+ - **Dates:** search results carry absolute dates (`[2026-03-04]`), never relative
132
+ times, so the text does not change as time passes.
133
+
134
+ The system prompt and earlier turns therefore never change, and provider prompt
135
+ caches keep hitting. The only exception is a profile that loads late (its first
136
+ fetch failed), which changes the system prefix once.
137
+
138
+ ### Injection modes
139
+
140
+ | Mode | Behavior |
141
+ | ---------- | -------- |
142
+ | `"auto"` | Default. Same as `"user"`. |
143
+ | `"user"` | Appends each turn's search results to that turn's user message (cache-safe). |
144
+ | `"system"` | Rewrites this integration's search block in the system message every user turn, next to the profile block. Prompt caching does not apply. |
145
+
146
+ ### Speech-to-speech models
147
+
148
+ Gemini Live and OpenAI Realtime read only the first context they receive from
149
+ Pipecat (0.0.98 through 1.7.0): apart from reconnects, later context frames only
150
+ forward new tool results, so neither a changed system message nor a new text user message reaches
151
+ the model mid-session, in any `inject_mode`. The default still gives these models
152
+ the profile, because it is fetched on the first context frame and is part of the
153
+ system instruction they start with. Per-turn search results do not reach them.
154
+ If you pass `system_instruction=` to `GeminiLiveLLMService`, Pipecat 1.x uses that
155
+ instead of the context's system message, so the profile is not included.
156
+
157
+ ### Timeouts and failures
158
+
159
+ Recall waits at most 3 seconds (`RECALL_TIMEOUT_SECONDS`). Profile and search run
160
+ in parallel with no SDK retries; if either fails or times out, the turn continues
161
+ without it. A failed profile is fetched again on the next new user turn, and a
162
+ failed search is not cached as a result for later turns.
163
+
164
+ Every request to Supermemory sends `x-sm-source: pipecat-python` and
165
+ `x-sm-plugin-version` (this package's installed version).
114
166
 
115
167
  ## How It Works
116
168
 
117
169
  1. **Intercepts context frames** - Listens for Pipecat's universal `LLMContextFrame` (and legacy 0.x frames)
118
- 2. **Tracks conversation** - Separates real conversation messages from tagged memory context
119
- 3. **Retrieves memories** - Reads the v5 profile and, in `query` or `full` mode, searches the same namespace for the user's message
120
- 4. **Injects memories** - Uses a system message for audio/system mode and a tagged user message otherwise
121
- 5. **Stores messages** - Serializes newly observed user and assistant messages through a background queue that drains during cleanup
170
+ 2. **Keys turns** - Identifies each user turn by its text and the reply before it, ignoring tagged memory blocks
171
+ 3. **Retrieves memories** - Reads the v5 profile once and, in `query` or `full` mode, searches the same namespace for each new user message
172
+ 4. **Injects memories** - Puts the profile block in the system message and each turn's search block on its user message
173
+ 5. **Stores messages** - Saves each finished turn, including its final reply, through a background queue
122
174
 
123
175
  ### What Gets Stored
124
176
 
125
- New user and assistant messages are stored as a JSON conversation segment. The
126
- injected `<user_memories>` message is filtered out before storage and does not
127
- advance the storage cursor.
177
+ Each finished turn (the user message, any tool calls and results, and the final
178
+ assistant reply) is stored as a JSON conversation segment once the next user turn
179
+ starts, and the last turn is stored during cleanup. System messages and the
180
+ injected `<user_memories>` blocks are left out. Saves never block the LLM call;
181
+ on cleanup the service waits at most `storage_drain_timeout` for pending writes.
128
182
 
129
183
  For example, this conversation segment:
130
184
 
@@ -180,7 +234,7 @@ async def websocket_endpoint(websocket: WebSocket):
180
234
  context = LLMContext([{"role": "system", "content": "You are a helpful assistant."}])
181
235
  context_aggregator = llm.create_context_aggregator(context)
182
236
 
183
- # Supermemory memory service
237
+ # The profile reaches Gemini Live through the opening system instruction
184
238
  memory = SupermemoryPipecatService(
185
239
  user_id="alice",
186
240
  session_id="session-123",
@@ -67,7 +67,8 @@ memory = SupermemoryPipecatService(
67
67
  search_limit=10, # Max memories to retrieve
68
68
  search_threshold=0.1, # Similarity threshold
69
69
  mode="full", # "profile", "query", or "full"
70
- inject_mode="auto", # "auto", "system", or "user"
70
+ inject_mode="auto", # "auto", "user", or "system"
71
+ storage_drain_timeout=3.0, # Seconds cleanup waits for pending writes
71
72
  system_prompt="Based on previous conversations, I recall:\n\n",
72
73
  ),
73
74
  )
@@ -75,25 +76,78 @@ memory = SupermemoryPipecatService(
75
76
 
76
77
  ### Memory Modes
77
78
 
78
- | Mode | Static Profile | Dynamic Profile | Search Results |
79
- | ----------- | -------------- | --------------- | -------------- |
80
- | `"profile"` | Yes | Yes | No |
81
- | `"query"` | No | No | Yes |
82
- | `"full"` | Yes | Yes | Yes |
79
+ | Mode | Profile block (system message) | Search block (user message) |
80
+ | ----------- | ------------------------------ | --------------------------- |
81
+ | `"profile"` | Yes | No |
82
+ | `"query"` | No | Yes |
83
+ | `"full"` | Yes | Yes |
84
+
85
+ ### Where memories go
86
+
87
+ - **Profile:** fetched once per conversation, on the first context frame (even
88
+ before the first user message), and appended as a `<user_memories>` block to the
89
+ first system message, or sent as a new leading system message when there is
90
+ none. It is never refreshed, so it stays byte-identical on every later request,
91
+ and it never appears in a user message.
92
+ - **Search results:** each user turn is searched once, and the results are
93
+ appended as a `<user_memories>` block to the user message they were retrieved
94
+ for. Earlier user messages keep the block they first received. Results the
95
+ profile already covers are skipped.
96
+ - **Tool calls:** steps inside a turn reuse that turn's block and never search again.
97
+ - **Turn identity:** a turn is keyed by its text plus the assistant reply before it,
98
+ so a repeated question after a new reply is a new turn with its own search, and
99
+ trimming old history from the front keeps every kept message's block.
100
+ - **Dates:** search results carry absolute dates (`[2026-03-04]`), never relative
101
+ times, so the text does not change as time passes.
102
+
103
+ The system prompt and earlier turns therefore never change, and provider prompt
104
+ caches keep hitting. The only exception is a profile that loads late (its first
105
+ fetch failed), which changes the system prefix once.
106
+
107
+ ### Injection modes
108
+
109
+ | Mode | Behavior |
110
+ | ---------- | -------- |
111
+ | `"auto"` | Default. Same as `"user"`. |
112
+ | `"user"` | Appends each turn's search results to that turn's user message (cache-safe). |
113
+ | `"system"` | Rewrites this integration's search block in the system message every user turn, next to the profile block. Prompt caching does not apply. |
114
+
115
+ ### Speech-to-speech models
116
+
117
+ Gemini Live and OpenAI Realtime read only the first context they receive from
118
+ Pipecat (0.0.98 through 1.7.0): apart from reconnects, later context frames only
119
+ forward new tool results, so neither a changed system message nor a new text user message reaches
120
+ the model mid-session, in any `inject_mode`. The default still gives these models
121
+ the profile, because it is fetched on the first context frame and is part of the
122
+ system instruction they start with. Per-turn search results do not reach them.
123
+ If you pass `system_instruction=` to `GeminiLiveLLMService`, Pipecat 1.x uses that
124
+ instead of the context's system message, so the profile is not included.
125
+
126
+ ### Timeouts and failures
127
+
128
+ Recall waits at most 3 seconds (`RECALL_TIMEOUT_SECONDS`). Profile and search run
129
+ in parallel with no SDK retries; if either fails or times out, the turn continues
130
+ without it. A failed profile is fetched again on the next new user turn, and a
131
+ failed search is not cached as a result for later turns.
132
+
133
+ Every request to Supermemory sends `x-sm-source: pipecat-python` and
134
+ `x-sm-plugin-version` (this package's installed version).
83
135
 
84
136
  ## How It Works
85
137
 
86
138
  1. **Intercepts context frames** - Listens for Pipecat's universal `LLMContextFrame` (and legacy 0.x frames)
87
- 2. **Tracks conversation** - Separates real conversation messages from tagged memory context
88
- 3. **Retrieves memories** - Reads the v5 profile and, in `query` or `full` mode, searches the same namespace for the user's message
89
- 4. **Injects memories** - Uses a system message for audio/system mode and a tagged user message otherwise
90
- 5. **Stores messages** - Serializes newly observed user and assistant messages through a background queue that drains during cleanup
139
+ 2. **Keys turns** - Identifies each user turn by its text and the reply before it, ignoring tagged memory blocks
140
+ 3. **Retrieves memories** - Reads the v5 profile once and, in `query` or `full` mode, searches the same namespace for each new user message
141
+ 4. **Injects memories** - Puts the profile block in the system message and each turn's search block on its user message
142
+ 5. **Stores messages** - Saves each finished turn, including its final reply, through a background queue
91
143
 
92
144
  ### What Gets Stored
93
145
 
94
- New user and assistant messages are stored as a JSON conversation segment. The
95
- injected `<user_memories>` message is filtered out before storage and does not
96
- advance the storage cursor.
146
+ Each finished turn (the user message, any tool calls and results, and the final
147
+ assistant reply) is stored as a JSON conversation segment once the next user turn
148
+ starts, and the last turn is stored during cleanup. System messages and the
149
+ injected `<user_memories>` blocks are left out. Saves never block the LLM call;
150
+ on cleanup the service waits at most `storage_drain_timeout` for pending writes.
97
151
 
98
152
  For example, this conversation segment:
99
153
 
@@ -149,7 +203,7 @@ async def websocket_endpoint(websocket: WebSocket):
149
203
  context = LLMContext([{"role": "system", "content": "You are a helpful assistant."}])
150
204
  context_aggregator = llm.create_context_aggregator(context)
151
205
 
152
- # Supermemory memory service
206
+ # The profile reaches Gemini Live through the opening system instruction
153
207
  memory = SupermemoryPipecatService(
154
208
  user_id="alice",
155
209
  session_id="session-123",
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "supermemory-pipecat"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "Supermemory integration for Pipecat - memory-enhanced conversational AI pipelines"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -25,8 +25,6 @@ Example:
25
25
  ```
26
26
  """
27
27
 
28
- from importlib.metadata import PackageNotFoundError, version
29
-
30
28
  from .exceptions import (
31
29
  APIError,
32
30
  ConfigurationError,
@@ -35,7 +33,7 @@ from .exceptions import (
35
33
  NetworkError,
36
34
  SupermemoryPipecatError,
37
35
  )
38
- from .service import SupermemoryPipecatService
36
+ from .service import PLUGIN_VERSION, SupermemoryPipecatService
39
37
  from .utils import (
40
38
  deduplicate_memories,
41
39
  format_memories_to_text,
@@ -44,11 +42,7 @@ from .utils import (
44
42
 
45
43
  InputParams = SupermemoryPipecatService.InputParams
46
44
 
47
- try:
48
- __version__ = version("supermemory-pipecat")
49
- except PackageNotFoundError:
50
- # Source-tree fallback; built wheels always use package metadata above.
51
- __version__ = "0.2.0"
45
+ __version__ = PLUGIN_VERSION
52
46
 
53
47
  __all__ = [
54
48
  # Main service