supermemory-pipecat 0.1.0__py3-none-any.whl
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/__init__.py +59 -0
- supermemory_pipecat/exceptions.py +58 -0
- supermemory_pipecat/service.py +364 -0
- supermemory_pipecat/utils.py +66 -0
- supermemory_pipecat-0.1.0.dist-info/METADATA +190 -0
- supermemory_pipecat-0.1.0.dist-info/RECORD +7 -0
- supermemory_pipecat-0.1.0.dist-info/WHEEL +4 -0
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
"""Supermemory Pipecat SDK - Memory-enhanced conversational AI pipelines.
|
|
2
|
+
|
|
3
|
+
This package provides seamless integration between Supermemory and Pipecat,
|
|
4
|
+
enabling persistent memory and context enhancement for voice AI applications.
|
|
5
|
+
|
|
6
|
+
Example:
|
|
7
|
+
```python
|
|
8
|
+
from supermemory_pipecat import SupermemoryPipecatService
|
|
9
|
+
|
|
10
|
+
# Create memory service
|
|
11
|
+
memory = SupermemoryPipecatService(
|
|
12
|
+
api_key=os.getenv("SUPERMEMORY_API_KEY"),
|
|
13
|
+
user_id="user-123",
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
# Add to Pipecat pipeline
|
|
17
|
+
pipeline = Pipeline([
|
|
18
|
+
transport.input(),
|
|
19
|
+
stt,
|
|
20
|
+
user_context,
|
|
21
|
+
memory, # Automatically retrieves and injects memories
|
|
22
|
+
llm,
|
|
23
|
+
transport.output(),
|
|
24
|
+
])
|
|
25
|
+
```
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from .service import SupermemoryPipecatService
|
|
29
|
+
from .exceptions import (
|
|
30
|
+
SupermemoryPipecatError,
|
|
31
|
+
ConfigurationError,
|
|
32
|
+
MemoryRetrievalError,
|
|
33
|
+
MemoryStorageError,
|
|
34
|
+
APIError,
|
|
35
|
+
NetworkError,
|
|
36
|
+
)
|
|
37
|
+
from .utils import (
|
|
38
|
+
get_last_user_message,
|
|
39
|
+
deduplicate_memories,
|
|
40
|
+
format_memories_to_text,
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
__version__ = "0.1.0"
|
|
44
|
+
|
|
45
|
+
__all__ = [
|
|
46
|
+
# Main service
|
|
47
|
+
"SupermemoryPipecatService",
|
|
48
|
+
# Exceptions
|
|
49
|
+
"SupermemoryPipecatError",
|
|
50
|
+
"ConfigurationError",
|
|
51
|
+
"MemoryRetrievalError",
|
|
52
|
+
"MemoryStorageError",
|
|
53
|
+
"APIError",
|
|
54
|
+
"NetworkError",
|
|
55
|
+
# Utilities
|
|
56
|
+
"get_last_user_message",
|
|
57
|
+
"deduplicate_memories",
|
|
58
|
+
"format_memories_to_text",
|
|
59
|
+
]
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
"""Custom exceptions for Supermemory Pipecat integration."""
|
|
2
|
+
|
|
3
|
+
from typing import Optional
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class SupermemoryPipecatError(Exception):
|
|
7
|
+
"""Base exception for all Supermemory Pipecat errors."""
|
|
8
|
+
|
|
9
|
+
def __init__(self, message: str, original_error: Optional[Exception] = None):
|
|
10
|
+
super().__init__(message)
|
|
11
|
+
self.message = message
|
|
12
|
+
self.original_error = original_error
|
|
13
|
+
|
|
14
|
+
def __str__(self) -> str:
|
|
15
|
+
if self.original_error:
|
|
16
|
+
return f"{self.message}: {self.original_error}"
|
|
17
|
+
return self.message
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class ConfigurationError(SupermemoryPipecatError):
|
|
21
|
+
"""Raised when there are configuration issues (e.g., missing API key, invalid params)."""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class MemoryRetrievalError(SupermemoryPipecatError):
|
|
25
|
+
"""Raised when memory retrieval operations fail."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class MemoryStorageError(SupermemoryPipecatError):
|
|
29
|
+
"""Raised when memory storage operations fail."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class APIError(SupermemoryPipecatError):
|
|
33
|
+
"""Raised when Supermemory API requests fail."""
|
|
34
|
+
|
|
35
|
+
def __init__(
|
|
36
|
+
self,
|
|
37
|
+
message: str,
|
|
38
|
+
status_code: Optional[int] = None,
|
|
39
|
+
response_text: Optional[str] = None,
|
|
40
|
+
original_error: Optional[Exception] = None,
|
|
41
|
+
):
|
|
42
|
+
super().__init__(message, original_error)
|
|
43
|
+
self.status_code = status_code
|
|
44
|
+
self.response_text = response_text
|
|
45
|
+
|
|
46
|
+
def __str__(self) -> str:
|
|
47
|
+
parts = [self.message]
|
|
48
|
+
if self.status_code:
|
|
49
|
+
parts.append(f"Status: {self.status_code}")
|
|
50
|
+
if self.response_text:
|
|
51
|
+
parts.append(f"Response: {self.response_text}")
|
|
52
|
+
if self.original_error:
|
|
53
|
+
parts.append(f"Cause: {self.original_error}")
|
|
54
|
+
return " | ".join(parts)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class NetworkError(SupermemoryPipecatError):
|
|
58
|
+
"""Raised when network operations fail."""
|
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
"""Supermemory Pipecat service integration.
|
|
2
|
+
|
|
3
|
+
This module provides a memory service that integrates with Supermemory to store
|
|
4
|
+
and retrieve conversational memories, enhancing LLM context with relevant
|
|
5
|
+
historical information.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import asyncio
|
|
9
|
+
import json
|
|
10
|
+
import os
|
|
11
|
+
from typing import Any, Dict, List, Literal, Optional
|
|
12
|
+
|
|
13
|
+
from loguru import logger
|
|
14
|
+
from pydantic import BaseModel, Field
|
|
15
|
+
|
|
16
|
+
from pipecat.frames.frames import Frame, LLMContextFrame, LLMMessagesFrame
|
|
17
|
+
from pipecat.processors.aggregators.llm_context import LLMContext
|
|
18
|
+
from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContextFrame
|
|
19
|
+
from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
|
|
20
|
+
|
|
21
|
+
from .exceptions import (
|
|
22
|
+
ConfigurationError,
|
|
23
|
+
MemoryRetrievalError,
|
|
24
|
+
)
|
|
25
|
+
from .utils import (
|
|
26
|
+
deduplicate_memories,
|
|
27
|
+
format_memories_to_text,
|
|
28
|
+
get_last_user_message,
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
try:
|
|
32
|
+
import supermemory
|
|
33
|
+
except ImportError:
|
|
34
|
+
supermemory = None # type: ignore
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class SupermemoryPipecatService(FrameProcessor):
|
|
38
|
+
"""A memory service that integrates Supermemory with Pipecat pipelines.
|
|
39
|
+
|
|
40
|
+
This service intercepts message frames in the pipeline, retrieves relevant
|
|
41
|
+
memories from Supermemory, enhances the context, and optionally stores
|
|
42
|
+
new conversations.
|
|
43
|
+
|
|
44
|
+
Example:
|
|
45
|
+
```python
|
|
46
|
+
from supermemory_pipecat import SupermemoryPipecatService
|
|
47
|
+
|
|
48
|
+
memory = SupermemoryPipecatService(
|
|
49
|
+
api_key=os.getenv("SUPERMEMORY_API_KEY"),
|
|
50
|
+
user_id="user-123",
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
pipeline = Pipeline([
|
|
54
|
+
transport.input(),
|
|
55
|
+
stt,
|
|
56
|
+
user_context,
|
|
57
|
+
memory, # Memory service enhances context here
|
|
58
|
+
llm,
|
|
59
|
+
transport.output(),
|
|
60
|
+
])
|
|
61
|
+
```
|
|
62
|
+
"""
|
|
63
|
+
|
|
64
|
+
class InputParams(BaseModel):
|
|
65
|
+
"""Configuration parameters for Supermemory Pipecat service.
|
|
66
|
+
|
|
67
|
+
Parameters:
|
|
68
|
+
search_limit: Maximum number of memories to retrieve per query.
|
|
69
|
+
search_threshold: Minimum similarity threshold for memory retrieval.
|
|
70
|
+
system_prompt: Prefix text for memory context messages.
|
|
71
|
+
mode: Memory retrieval mode - "profile", "query", or "full".
|
|
72
|
+
"""
|
|
73
|
+
|
|
74
|
+
search_limit: int = Field(default=10, ge=1)
|
|
75
|
+
search_threshold: float = Field(default=0.1, ge=0.0, le=1.0)
|
|
76
|
+
system_prompt: str = Field(default="Based on previous conversations, I recall:\n\n")
|
|
77
|
+
mode: Literal["profile", "query", "full"] = Field(default="full")
|
|
78
|
+
|
|
79
|
+
def __init__(
|
|
80
|
+
self,
|
|
81
|
+
*,
|
|
82
|
+
api_key: Optional[str] = None,
|
|
83
|
+
user_id: str,
|
|
84
|
+
session_id: Optional[str] = None,
|
|
85
|
+
params: Optional[InputParams] = None,
|
|
86
|
+
base_url: Optional[str] = None,
|
|
87
|
+
):
|
|
88
|
+
"""Initialize the Supermemory Pipecat service.
|
|
89
|
+
|
|
90
|
+
Args:
|
|
91
|
+
api_key: The API key for Supermemory. Falls back to SUPERMEMORY_API_KEY env var.
|
|
92
|
+
user_id: The user ID - used as container_tag for memory scoping (REQUIRED).
|
|
93
|
+
session_id: Session/conversation ID for grouping memories (optional).
|
|
94
|
+
params: Configuration parameters for memory retrieval and storage.
|
|
95
|
+
base_url: Optional custom base URL for Supermemory API.
|
|
96
|
+
|
|
97
|
+
Raises:
|
|
98
|
+
ConfigurationError: If API key is missing or user_id not provided.
|
|
99
|
+
"""
|
|
100
|
+
super().__init__()
|
|
101
|
+
|
|
102
|
+
# Get API key
|
|
103
|
+
self.api_key = api_key or os.getenv("SUPERMEMORY_API_KEY")
|
|
104
|
+
if not self.api_key:
|
|
105
|
+
raise ConfigurationError(
|
|
106
|
+
"API key is required. Provide api_key parameter or set SUPERMEMORY_API_KEY environment variable."
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
# user_id is required and used directly as container_tag
|
|
110
|
+
if not user_id:
|
|
111
|
+
raise ConfigurationError("user_id is required")
|
|
112
|
+
|
|
113
|
+
self.user_id = user_id
|
|
114
|
+
self.container_tag = user_id # container_tag = user_id directly
|
|
115
|
+
self.session_id = session_id # optional session/conversation ID
|
|
116
|
+
|
|
117
|
+
# Configuration
|
|
118
|
+
self.params = params or SupermemoryPipecatService.InputParams()
|
|
119
|
+
|
|
120
|
+
# Initialize async Supermemory client
|
|
121
|
+
self._supermemory_client = None
|
|
122
|
+
if supermemory is not None:
|
|
123
|
+
try:
|
|
124
|
+
self._supermemory_client = supermemory.AsyncSupermemory(
|
|
125
|
+
api_key=self.api_key,
|
|
126
|
+
base_url=base_url,
|
|
127
|
+
)
|
|
128
|
+
except Exception as e:
|
|
129
|
+
logger.warning(f"Failed to initialize Supermemory client: {e}")
|
|
130
|
+
|
|
131
|
+
# Track how many messages we've already sent to memory
|
|
132
|
+
self._messages_sent_count: int = 0
|
|
133
|
+
|
|
134
|
+
# Track last query to avoid duplicate processing
|
|
135
|
+
self._last_query: Optional[str] = None
|
|
136
|
+
|
|
137
|
+
logger.info(
|
|
138
|
+
f"Initialized SupermemoryPipecatService with "
|
|
139
|
+
f"user_id={user_id}, session_id={session_id}"
|
|
140
|
+
)
|
|
141
|
+
|
|
142
|
+
async def _retrieve_memories(self, query: str) -> Dict[str, Any]:
|
|
143
|
+
"""Retrieve relevant memories from Supermemory.
|
|
144
|
+
|
|
145
|
+
Args:
|
|
146
|
+
query: The query to search for relevant memories.
|
|
147
|
+
|
|
148
|
+
Returns:
|
|
149
|
+
Dictionary containing profile and search results.
|
|
150
|
+
"""
|
|
151
|
+
if self._supermemory_client is None:
|
|
152
|
+
raise MemoryRetrievalError(
|
|
153
|
+
"Supermemory client not initialized. Install with: pip install supermemory"
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
try:
|
|
157
|
+
logger.debug(f"Retrieving memories for query: {query[:100]}...")
|
|
158
|
+
|
|
159
|
+
# Build kwargs for profile request
|
|
160
|
+
kwargs: Dict[str, Any] = {
|
|
161
|
+
"container_tag": self.container_tag,
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
# Add query for search modes
|
|
165
|
+
if self.params.mode != "profile" and query:
|
|
166
|
+
kwargs["q"] = query
|
|
167
|
+
kwargs["threshold"] = self.params.search_threshold
|
|
168
|
+
# Pass limit via extra_body since SDK doesn't have direct param
|
|
169
|
+
kwargs["extra_body"] = {"limit": self.params.search_limit}
|
|
170
|
+
|
|
171
|
+
# Use SDK's profile method
|
|
172
|
+
response = await self._supermemory_client.profile(**kwargs)
|
|
173
|
+
|
|
174
|
+
# Extract memory strings from SDK response
|
|
175
|
+
search_results = []
|
|
176
|
+
if response.search_results and response.search_results.results:
|
|
177
|
+
search_results = [r["memory"] for r in response.search_results.results]
|
|
178
|
+
|
|
179
|
+
data: Dict[str, Any] = {
|
|
180
|
+
"profile": {
|
|
181
|
+
"static": response.profile.static,
|
|
182
|
+
"dynamic": response.profile.dynamic,
|
|
183
|
+
},
|
|
184
|
+
"search_results": search_results,
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
logger.debug(
|
|
188
|
+
f"Retrieved memories - static: {len(data['profile']['static'])}, "
|
|
189
|
+
f"dynamic: {len(data['profile']['dynamic'])}, "
|
|
190
|
+
f"search: {len(data['search_results'])}"
|
|
191
|
+
)
|
|
192
|
+
return data
|
|
193
|
+
|
|
194
|
+
except Exception as e:
|
|
195
|
+
logger.error(f"Error retrieving memories: {e}")
|
|
196
|
+
raise MemoryRetrievalError("Failed to retrieve memories", e)
|
|
197
|
+
|
|
198
|
+
async def _store_messages(self, messages: List[Dict[str, Any]]) -> None:
|
|
199
|
+
"""Store messages in Supermemory.
|
|
200
|
+
|
|
201
|
+
Args:
|
|
202
|
+
messages: List of message dicts with 'role' and 'content' keys.
|
|
203
|
+
"""
|
|
204
|
+
if self._supermemory_client is None:
|
|
205
|
+
logger.warning("Supermemory client not initialized, skipping memory storage")
|
|
206
|
+
return
|
|
207
|
+
|
|
208
|
+
if not messages:
|
|
209
|
+
return
|
|
210
|
+
|
|
211
|
+
try:
|
|
212
|
+
# Format messages as JSON array
|
|
213
|
+
formatted_content = json.dumps(messages)
|
|
214
|
+
|
|
215
|
+
logger.debug(f"Storing {len(messages)} messages to Supermemory")
|
|
216
|
+
|
|
217
|
+
# Build storage params
|
|
218
|
+
add_params: Dict[str, Any] = {
|
|
219
|
+
"content": formatted_content,
|
|
220
|
+
"container_tags": [self.container_tag],
|
|
221
|
+
"metadata": {"platform": "pipecat"},
|
|
222
|
+
}
|
|
223
|
+
if self.session_id:
|
|
224
|
+
add_params["custom_id"] = f"{self.session_id}"
|
|
225
|
+
|
|
226
|
+
await self._supermemory_client.memories.add(**add_params)
|
|
227
|
+
logger.debug(f"Successfully stored {len(messages)} messages in Supermemory")
|
|
228
|
+
|
|
229
|
+
except Exception as e:
|
|
230
|
+
# Don't fail the pipeline on storage errors
|
|
231
|
+
logger.error(f"Error storing messages in Supermemory: {e}")
|
|
232
|
+
|
|
233
|
+
def _enhance_context_with_memories(
|
|
234
|
+
self,
|
|
235
|
+
context: LLMContext,
|
|
236
|
+
query: str,
|
|
237
|
+
memories_data: Dict[str, Any],
|
|
238
|
+
) -> None:
|
|
239
|
+
"""Enhance the LLM context with relevant memories.
|
|
240
|
+
|
|
241
|
+
Args:
|
|
242
|
+
context: The LLM context to enhance.
|
|
243
|
+
query: The query used for retrieval.
|
|
244
|
+
memories_data: Raw memory data from Supermemory API.
|
|
245
|
+
"""
|
|
246
|
+
# Skip if same query (avoid duplicate processing)
|
|
247
|
+
if self._last_query == query:
|
|
248
|
+
return
|
|
249
|
+
|
|
250
|
+
self._last_query = query
|
|
251
|
+
|
|
252
|
+
# Extract and deduplicate memories
|
|
253
|
+
profile = memories_data["profile"]
|
|
254
|
+
|
|
255
|
+
deduplicated = deduplicate_memories(
|
|
256
|
+
static=profile["static"],
|
|
257
|
+
dynamic=profile["dynamic"],
|
|
258
|
+
search_results=memories_data["search_results"],
|
|
259
|
+
)
|
|
260
|
+
|
|
261
|
+
# Check if we have any memories
|
|
262
|
+
total_memories = (
|
|
263
|
+
len(deduplicated["static"])
|
|
264
|
+
+ len(deduplicated["dynamic"])
|
|
265
|
+
+ len(deduplicated["search_results"])
|
|
266
|
+
)
|
|
267
|
+
|
|
268
|
+
if total_memories == 0:
|
|
269
|
+
logger.debug("No memories found to inject")
|
|
270
|
+
return
|
|
271
|
+
|
|
272
|
+
# Format memories based on mode
|
|
273
|
+
include_profile = self.params.mode in ("profile", "full")
|
|
274
|
+
include_search = self.params.mode in ("query", "full")
|
|
275
|
+
|
|
276
|
+
memory_text = format_memories_to_text(
|
|
277
|
+
deduplicated,
|
|
278
|
+
system_prompt=self.params.system_prompt,
|
|
279
|
+
include_static=include_profile,
|
|
280
|
+
include_dynamic=include_profile,
|
|
281
|
+
include_search=include_search,
|
|
282
|
+
)
|
|
283
|
+
|
|
284
|
+
if not memory_text:
|
|
285
|
+
return
|
|
286
|
+
|
|
287
|
+
# Inject memories into context as user message
|
|
288
|
+
context.add_message({"role": "user", "content": memory_text})
|
|
289
|
+
|
|
290
|
+
logger.debug(f"Enhanced context with {total_memories} memories")
|
|
291
|
+
|
|
292
|
+
async def process_frame(self, frame: Frame, direction: FrameDirection) -> None:
|
|
293
|
+
"""Process incoming frames, intercept context frames for memory integration.
|
|
294
|
+
|
|
295
|
+
Args:
|
|
296
|
+
frame: The incoming frame to process.
|
|
297
|
+
direction: The direction of frame flow in the pipeline.
|
|
298
|
+
"""
|
|
299
|
+
await super().process_frame(frame, direction)
|
|
300
|
+
|
|
301
|
+
context = None
|
|
302
|
+
messages = None
|
|
303
|
+
|
|
304
|
+
# Handle different frame types
|
|
305
|
+
if isinstance(frame, (LLMContextFrame, OpenAILLMContextFrame)):
|
|
306
|
+
context = frame.context
|
|
307
|
+
elif isinstance(frame, LLMMessagesFrame):
|
|
308
|
+
messages = frame.messages
|
|
309
|
+
context = LLMContext(messages)
|
|
310
|
+
|
|
311
|
+
if context:
|
|
312
|
+
try:
|
|
313
|
+
# Get messages from context
|
|
314
|
+
context_messages = context.get_messages()
|
|
315
|
+
latest_user_message = get_last_user_message(context_messages)
|
|
316
|
+
|
|
317
|
+
if latest_user_message:
|
|
318
|
+
# Retrieve memories from Supermemory
|
|
319
|
+
try:
|
|
320
|
+
memories_data = await self._retrieve_memories(latest_user_message)
|
|
321
|
+
self._enhance_context_with_memories(
|
|
322
|
+
context, latest_user_message, memories_data
|
|
323
|
+
)
|
|
324
|
+
except MemoryRetrievalError as e:
|
|
325
|
+
logger.warning(f"Memory retrieval failed, continuing without memories: {e}")
|
|
326
|
+
|
|
327
|
+
# Store unsent messages (user and assistant only, skip system)
|
|
328
|
+
storable_messages = [
|
|
329
|
+
msg for msg in context_messages if msg["role"] in ("user", "assistant")
|
|
330
|
+
]
|
|
331
|
+
unsent_messages = storable_messages[self._messages_sent_count :]
|
|
332
|
+
|
|
333
|
+
if unsent_messages:
|
|
334
|
+
asyncio.create_task(self._store_messages(unsent_messages))
|
|
335
|
+
self._messages_sent_count = len(storable_messages)
|
|
336
|
+
|
|
337
|
+
# Pass the frame downstream
|
|
338
|
+
if messages is not None:
|
|
339
|
+
# For LLMMessagesFrame, create new frame with enhanced messages
|
|
340
|
+
await self.push_frame(LLMMessagesFrame(context.get_messages()))
|
|
341
|
+
else:
|
|
342
|
+
# For context frames, pass the enhanced frame
|
|
343
|
+
await self.push_frame(frame)
|
|
344
|
+
|
|
345
|
+
except Exception as e:
|
|
346
|
+
logger.error(f"Error processing frame with Supermemory: {e}")
|
|
347
|
+
# Still pass the original frame through on error
|
|
348
|
+
await self.push_frame(frame)
|
|
349
|
+
else:
|
|
350
|
+
# Non-context frames pass through unchanged
|
|
351
|
+
await self.push_frame(frame, direction)
|
|
352
|
+
|
|
353
|
+
def get_messages_sent_count(self) -> int:
|
|
354
|
+
"""Get the count of messages sent to memory.
|
|
355
|
+
|
|
356
|
+
Returns:
|
|
357
|
+
Number of messages already sent to Supermemory.
|
|
358
|
+
"""
|
|
359
|
+
return self._messages_sent_count
|
|
360
|
+
|
|
361
|
+
def reset_memory_tracking(self) -> None:
|
|
362
|
+
"""Reset memory tracking for a new conversation."""
|
|
363
|
+
self._messages_sent_count = 0
|
|
364
|
+
self._last_query = None
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Utility functions for Supermemory Pipecat integration."""
|
|
2
|
+
|
|
3
|
+
from typing import Dict, List
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def get_last_user_message(messages: List[Dict[str, str]]) -> str | None:
|
|
7
|
+
"""Extract the last user message content from a list of messages."""
|
|
8
|
+
for msg in reversed(messages):
|
|
9
|
+
if msg["role"] == "user":
|
|
10
|
+
return msg["content"]
|
|
11
|
+
return None
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def deduplicate_memories(
|
|
15
|
+
static: List[str],
|
|
16
|
+
dynamic: List[str],
|
|
17
|
+
search_results: List[str],
|
|
18
|
+
) -> Dict[str, List[str]]:
|
|
19
|
+
"""Deduplicate memories. Priority: static > dynamic > search."""
|
|
20
|
+
seen = set()
|
|
21
|
+
|
|
22
|
+
def unique(memories):
|
|
23
|
+
out = []
|
|
24
|
+
for m in memories:
|
|
25
|
+
if m not in seen:
|
|
26
|
+
seen.add(m)
|
|
27
|
+
out.append(m)
|
|
28
|
+
return out
|
|
29
|
+
|
|
30
|
+
return {
|
|
31
|
+
"static": unique(static),
|
|
32
|
+
"dynamic": unique(dynamic),
|
|
33
|
+
"search_results": unique(search_results),
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def format_memories_to_text(
|
|
38
|
+
memories: Dict[str, List[str]],
|
|
39
|
+
system_prompt: str = "Based on previous conversations, I recall:\n\n",
|
|
40
|
+
include_static: bool = True,
|
|
41
|
+
include_dynamic: bool = True,
|
|
42
|
+
include_search: bool = True,
|
|
43
|
+
) -> str:
|
|
44
|
+
"""Format deduplicated memories into a text string for injection."""
|
|
45
|
+
sections = []
|
|
46
|
+
|
|
47
|
+
static = memories["static"]
|
|
48
|
+
dynamic = memories["dynamic"]
|
|
49
|
+
search_results = memories["search_results"]
|
|
50
|
+
|
|
51
|
+
if include_static and static:
|
|
52
|
+
sections.append("## User Profile (Persistent)")
|
|
53
|
+
sections.append("\n".join(f"- {item}" for item in static))
|
|
54
|
+
|
|
55
|
+
if include_dynamic and dynamic:
|
|
56
|
+
sections.append("## Recent Context")
|
|
57
|
+
sections.append("\n".join(f"- {item}" for item in dynamic))
|
|
58
|
+
|
|
59
|
+
if include_search and search_results:
|
|
60
|
+
sections.append("## Relevant Memories")
|
|
61
|
+
sections.append("\n".join(f"- {item}" for item in search_results))
|
|
62
|
+
|
|
63
|
+
if not sections:
|
|
64
|
+
return ""
|
|
65
|
+
|
|
66
|
+
return f"{system_prompt}\n" + "\n\n".join(sections)
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: supermemory-pipecat
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Supermemory integration for Pipecat - memory-enhanced conversational AI pipelines
|
|
5
|
+
Project-URL: Homepage, https://supermemory.ai
|
|
6
|
+
Project-URL: Documentation, https://docs.supermemory.ai
|
|
7
|
+
Project-URL: Repository, https://github.com/supermemoryai/supermemory
|
|
8
|
+
Author-email: Supermemory <support@supermemory.ai>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
Keywords: conversational-ai,llm,memory,pipecat,supermemory,voice-ai
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Requires-Dist: loguru>=0.7.3
|
|
21
|
+
Requires-Dist: pipecat-ai>=0.0.98
|
|
22
|
+
Requires-Dist: pydantic>=2.10.0
|
|
23
|
+
Requires-Dist: supermemory>=3.16.0
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: black>=24.8.0; extra == 'dev'
|
|
26
|
+
Requires-Dist: isort>=5.13.2; extra == 'dev'
|
|
27
|
+
Requires-Dist: mypy>=1.14.1; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest>=8.3.5; extra == 'dev'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# Supermemory Pipecat SDK
|
|
33
|
+
|
|
34
|
+
Memory-enhanced conversational AI pipelines with [Supermemory](https://supermemory.ai) and [Pipecat](https://github.com/pipecat-ai/pipecat).
|
|
35
|
+
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install supermemory-pipecat
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Quick Start
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import os
|
|
46
|
+
from pipecat.pipeline.pipeline import Pipeline
|
|
47
|
+
from pipecat.services.openai import OpenAILLMService, OpenAIUserContextAggregator
|
|
48
|
+
from supermemory_pipecat import SupermemoryPipecatService
|
|
49
|
+
|
|
50
|
+
# Create memory service
|
|
51
|
+
memory = SupermemoryPipecatService(
|
|
52
|
+
api_key=os.getenv("SUPERMEMORY_API_KEY"),
|
|
53
|
+
user_id="user-123", # Required: used as container_tag
|
|
54
|
+
session_id="conversation-456", # Optional: groups memories by session
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
# Create pipeline with memory
|
|
58
|
+
pipeline = Pipeline([
|
|
59
|
+
transport.input(),
|
|
60
|
+
stt,
|
|
61
|
+
user_context,
|
|
62
|
+
memory, # Automatically retrieves and injects relevant memories
|
|
63
|
+
llm,
|
|
64
|
+
transport.output(),
|
|
65
|
+
])
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Configuration
|
|
69
|
+
|
|
70
|
+
### Parameters
|
|
71
|
+
|
|
72
|
+
| Parameter | Type | Required | Description |
|
|
73
|
+
| ------------ | ----------- | -------- | ---------------------------------------------------------- |
|
|
74
|
+
| `user_id` | str | **Yes** | User identifier - used as container_tag for memory scoping |
|
|
75
|
+
| `session_id` | str | No | Session/conversation ID for grouping memories |
|
|
76
|
+
| `api_key` | str | No | Supermemory API key (or set `SUPERMEMORY_API_KEY` env var) |
|
|
77
|
+
| `params` | InputParams | No | Advanced configuration |
|
|
78
|
+
| `base_url` | str | No | Custom API endpoint |
|
|
79
|
+
|
|
80
|
+
### Advanced Configuration
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from supermemory_pipecat import SupermemoryPipecatService
|
|
84
|
+
|
|
85
|
+
memory = SupermemoryPipecatService(
|
|
86
|
+
user_id="user-123",
|
|
87
|
+
session_id="conv-456",
|
|
88
|
+
params=SupermemoryPipecatService.InputParams(
|
|
89
|
+
search_limit=10, # Max memories to retrieve
|
|
90
|
+
search_threshold=0.1, # Similarity threshold
|
|
91
|
+
mode="full", # "profile", "query", or "full"
|
|
92
|
+
system_prompt="Based on previous conversations, I recall:\n\n",
|
|
93
|
+
),
|
|
94
|
+
)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Memory Modes
|
|
98
|
+
|
|
99
|
+
| Mode | Static Profile | Dynamic Profile | Search Results |
|
|
100
|
+
| ----------- | -------------- | --------------- | -------------- |
|
|
101
|
+
| `"profile"` | Yes | Yes | No |
|
|
102
|
+
| `"query"` | No | No | Yes |
|
|
103
|
+
| `"full"` | Yes | Yes | Yes |
|
|
104
|
+
|
|
105
|
+
## How It Works
|
|
106
|
+
|
|
107
|
+
1. **Intercepts context frames** - Listens for `LLMContextFrame` in the pipeline
|
|
108
|
+
2. **Tracks conversation** - Maintains clean conversation history (no injected memories)
|
|
109
|
+
3. **Retrieves memories** - Queries `/v4/profile` API with user's message
|
|
110
|
+
4. **Injects memories** - Formats and adds to LLM context as system message
|
|
111
|
+
5. **Stores messages** - Sends last user message to Supermemory (background, non-blocking)
|
|
112
|
+
|
|
113
|
+
### What Gets Stored
|
|
114
|
+
|
|
115
|
+
Only the last user message is sent to Supermemory:
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
User: What's the weather like today?
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Stored as:
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"content": "User: What's the weather like today?",
|
|
126
|
+
"container_tags": ["user-123"],
|
|
127
|
+
"custom_id": "conversation-456",
|
|
128
|
+
"metadata": { "platform": "pipecat" }
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Full Example
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
import asyncio
|
|
136
|
+
import os
|
|
137
|
+
from fastapi import FastAPI, WebSocket
|
|
138
|
+
from pipecat.pipeline.pipeline import Pipeline
|
|
139
|
+
from pipecat.pipeline.task import PipelineTask
|
|
140
|
+
from pipecat.pipeline.runner import PipelineRunner
|
|
141
|
+
from pipecat.services.openai import (
|
|
142
|
+
OpenAILLMService,
|
|
143
|
+
OpenAIUserContextAggregator,
|
|
144
|
+
)
|
|
145
|
+
from pipecat.transports.network.fastapi_websocket import (
|
|
146
|
+
FastAPIWebsocketTransport,
|
|
147
|
+
FastAPIWebsocketParams,
|
|
148
|
+
)
|
|
149
|
+
from supermemory_pipecat import SupermemoryPipecatService
|
|
150
|
+
|
|
151
|
+
app = FastAPI()
|
|
152
|
+
|
|
153
|
+
@app.websocket("/chat")
|
|
154
|
+
async def websocket_endpoint(websocket: WebSocket):
|
|
155
|
+
await websocket.accept()
|
|
156
|
+
|
|
157
|
+
transport = FastAPIWebsocketTransport(
|
|
158
|
+
websocket=websocket,
|
|
159
|
+
params=FastAPIWebsocketParams(audio_out_enabled=True),
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
user_context = OpenAIUserContextAggregator()
|
|
163
|
+
|
|
164
|
+
# Supermemory memory service
|
|
165
|
+
memory = SupermemoryPipecatService(
|
|
166
|
+
user_id="alice",
|
|
167
|
+
session_id="session-123",
|
|
168
|
+
)
|
|
169
|
+
|
|
170
|
+
llm = OpenAILLMService(
|
|
171
|
+
api_key=os.getenv("OPENAI_API_KEY"),
|
|
172
|
+
model="gpt-4",
|
|
173
|
+
)
|
|
174
|
+
|
|
175
|
+
pipeline = Pipeline([
|
|
176
|
+
transport.input(),
|
|
177
|
+
user_context,
|
|
178
|
+
memory,
|
|
179
|
+
llm,
|
|
180
|
+
transport.output(),
|
|
181
|
+
])
|
|
182
|
+
|
|
183
|
+
runner = PipelineRunner()
|
|
184
|
+
task = PipelineTask(pipeline)
|
|
185
|
+
await runner.run(task)
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## License
|
|
189
|
+
|
|
190
|
+
MIT
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
supermemory_pipecat/__init__.py,sha256=VEX5CCQ3kHAfVZxkWpI3MhFVTQSxSxe07Q37gwhlGSo,1385
|
|
2
|
+
supermemory_pipecat/exceptions.py,sha256=izy5WAZy3hZWDvuBb0BcfUFF-wuwznrdvoDcKgzz8Wc,1789
|
|
3
|
+
supermemory_pipecat/service.py,sha256=jqNEmA-YGmJOgr9eTB2a2V4pY7LoTsNm5rLNRnLBBuM,13173
|
|
4
|
+
supermemory_pipecat/utils.py,sha256=vLYU7WXNRTDPh3wqrsWHJiINFP6YpEErt21ggDQEegs,1925
|
|
5
|
+
supermemory_pipecat-0.1.0.dist-info/METADATA,sha256=HCOuKO-drBmhfO96QZSFx2YvGU93OGhISflrexi3zDA,5918
|
|
6
|
+
supermemory_pipecat-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
7
|
+
supermemory_pipecat-0.1.0.dist-info/RECORD,,
|