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.
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/PKG-INFO +69 -15
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/README.md +68 -14
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/pyproject.toml +1 -1
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/src/supermemory_pipecat/__init__.py +2 -8
- supermemory_pipecat-0.3.0/src/supermemory_pipecat/service.py +605 -0
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/src/supermemory_pipecat/utils.py +19 -44
- supermemory_pipecat-0.3.0/tests/test_empty_profile.py +407 -0
- supermemory_pipecat-0.2.0/src/supermemory_pipecat/service.py +0 -528
- supermemory_pipecat-0.2.0/tests/test_empty_profile.py +0 -152
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/.gitignore +0 -0
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/src/supermemory_pipecat/exceptions.py +0 -0
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/tests/__init__.py +0 -0
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/tests/test_public_exports.py +0 -0
- {supermemory_pipecat-0.2.0 → supermemory_pipecat-0.3.0}/tests/test_utils.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: supermemory-pipecat
|
|
3
|
-
Version: 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", "
|
|
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 |
|
|
110
|
-
| ----------- |
|
|
111
|
-
| `"profile"` | Yes
|
|
112
|
-
| `"query"` | No
|
|
113
|
-
| `"full"` | 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. **
|
|
119
|
-
3. **Retrieves memories** - Reads the v5 profile and, in `query` or `full` mode, searches the same namespace for
|
|
120
|
-
4. **Injects memories** -
|
|
121
|
-
5. **Stores messages** -
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
#
|
|
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", "
|
|
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 |
|
|
79
|
-
| ----------- |
|
|
80
|
-
| `"profile"` | Yes
|
|
81
|
-
| `"query"` | No
|
|
82
|
-
| `"full"` | 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. **
|
|
88
|
-
3. **Retrieves memories** - Reads the v5 profile and, in `query` or `full` mode, searches the same namespace for
|
|
89
|
-
4. **Injects memories** -
|
|
90
|
-
5. **Stores messages** -
|
|
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
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
-
#
|
|
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",
|
|
@@ -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
|
-
|
|
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
|