pipecat-memorysync 1.1.1__tar.gz → 1.2.0__tar.gz

{pipecat_memorysync-1.1.1 → pipecat_memorysync-1.2.0}/.gitignore

@@ -1,5 +1,5 @@
-venv/
-__pycache__/
-.pytest_cache/
-dist/
-*.egg-info/
+venv/
+__pycache__/
+.pytest_cache/
+dist/
+*.egg-info/

{pipecat_memorysync-1.1.1 → pipecat_memorysync-1.2.0}/CHANGELOG.md

@@ -1,51 +1,51 @@
-# Changelog
-
-All notable changes to `pipecat-memorysync` are documented here.
-
-## 1.1.1 — 2026-08-29
-
-- **Immediate, loss-proof capture.** 1.1.0's turn-complete merging
-  deferred the current utterance until the turn completed — on a browser
-  disconnect that deferral raced the brief cancel salvage window and
-  could lose the newest (usually most important) turn over slow
-  networks. Capture is immediate again: every new user/assistant message
-  is in flight the moment its frame passes, BEFORE the LLM replies.
-  Junk filtering and fact extraction now happen server-side (the
-  platform's low-value gate + conversational ingestion), so client-side
-  merging is unnecessary. Suite: 17 checks on Pipecat v1.8.1, including
-  the exact disconnect sequence that previously lost data.
-
-## 1.1.0 — 2026-08-29
-
-- **Turn-complete capture.** Voice aggregators split one utterance across
-  several context messages at speech pauses; those fragments previously
-  stored as separate rows ("and", "dinner", …). Consecutive new user
-  fragments now merge into ONE verbatim turn, stored when the assistant
-  reply completes the turn; an in-progress utterance is flushed as one
-  merged turn at end of call. Assistant turns still store immediately,
-  and a failed store releases its fragments for retry on the next frame.
-- Delta-only and idempotency guarantees unchanged; suite grows to 17
-  checks on Pipecat v1.8.1 (fragment merging, end-of-call tail flush,
-  failed-store retry).
-
-## 1.0.1 — 2026-08-29
-
-- Metadata only: the source repository moved to
-  `https://github.com/memorysyncio/memorysync-pipecat`; project URLs updated.
-  No code changes.
-
-## 1.0.0 — 2026-08-29
-
-Initial release.
-
-- `MemorySyncMemoryService`, a `FrameProcessor` for the position between the
-  user context aggregator and the LLM service.
-- Budgeted memory recall (default 1.2 s hard timeout) injected into every
-  `LLMContextFrame` as a guarded system message — a slow or unreachable
-  backend degrades to an unenriched frame, never a stalled reply.
-- Delta-only capture with deterministic idempotency seeds: only turns not
-  seen before are persisted, with role fidelity for user and assistant.
-- Injection exclusion: the injected memory block is never re-captured.
-- Graceful `EndFrame` flush (bounded 3 s window) and `CancelFrame` salvage.
-- Tested with Pipecat v1.8.1 through `pipecat.tests.utils.run_test`
-  (14-test suite).
+# Changelog
+
+All notable changes to `pipecat-memorysync` are documented here.
+
+## 1.1.1 — 2026-08-29
+
+- **Immediate, loss-proof capture.** 1.1.0's turn-complete merging
+  deferred the current utterance until the turn completed — on a browser
+  disconnect that deferral raced the brief cancel salvage window and
+  could lose the newest (usually most important) turn over slow
+  networks. Capture is immediate again: every new user/assistant message
+  is in flight the moment its frame passes, BEFORE the LLM replies.
+  Junk filtering and fact extraction now happen server-side (the
+  platform's low-value gate + conversational ingestion), so client-side
+  merging is unnecessary. Suite: 17 checks on Pipecat v1.8.1, including
+  the exact disconnect sequence that previously lost data.
+
+## 1.1.0 — 2026-08-29
+
+- **Turn-complete capture.** Voice aggregators split one utterance across
+  several context messages at speech pauses; those fragments previously
+  stored as separate rows ("and", "dinner", …). Consecutive new user
+  fragments now merge into ONE verbatim turn, stored when the assistant
+  reply completes the turn; an in-progress utterance is flushed as one
+  merged turn at end of call. Assistant turns still store immediately,
+  and a failed store releases its fragments for retry on the next frame.
+- Delta-only and idempotency guarantees unchanged; suite grows to 17
+  checks on Pipecat v1.8.1 (fragment merging, end-of-call tail flush,
+  failed-store retry).
+
+## 1.0.1 — 2026-08-29
+
+- Metadata only: the source repository moved to
+  `https://github.com/memorysyncio/memorysync-pipecat`; project URLs updated.
+  No code changes.
+
+## 1.0.0 — 2026-08-29
+
+Initial release.
+
+- `MemorySyncMemoryService`, a `FrameProcessor` for the position between the
+  user context aggregator and the LLM service.
+- Budgeted memory recall (default 1.2 s hard timeout) injected into every
+  `LLMContextFrame` as a guarded system message — a slow or unreachable
+  backend degrades to an unenriched frame, never a stalled reply.
+- Delta-only capture with deterministic idempotency seeds: only turns not
+  seen before are persisted, with role fidelity for user and assistant.
+- Injection exclusion: the injected memory block is never re-captured.
+- Graceful `EndFrame` flush (bounded 3 s window) and `CancelFrame` salvage.
+- Tested with Pipecat v1.8.1 through `pipecat.tests.utils.run_test`
+  (14-test suite).

{pipecat_memorysync-1.1.1 → pipecat_memorysync-1.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: pipecat-memorysync
-Version: 1.1.1
-Summary: MemorySync for Pipecat: budgeted memory recall that never stalls a voice reply, delta-only conversation persistence with idempotency seeds, and a pipeline that cannot be broken by a memory outage.
+Version: 1.2.0
+Summary: MemorySync for Pipecat: budgeted memory recall that never stalls a voice reply, delta-only fact capture from the caller's turns with idempotency seeds, and a pipeline that cannot be broken by a memory outage.
 Project-URL: Homepage, https://docs.memorysync.io/guides/pipecat
 Project-URL: Documentation, https://docs.memorysync.io/guides/pipecat
 Project-URL: Repository, https://github.com/memorysyncio/memorysync-pipecat
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 
 [MemorySync](https://memorysync.io) for [Pipecat](https://github.com/pipecat-ai/pipecat) —
 long-term memory for voice pipelines that never stalls a reply and never
-re-stores what it already knows. PyPI package: **`pipecat-memorysync`**.
+re-sends a turn it already sent. PyPI package: **`pipecat-memorysync`**.
 
 Built and maintained by the [MemorySync](https://memorysync.io) team —
 MemorySync is our product, and this integration is actively maintained
@@ -73,28 +73,28 @@ pipeline = Pipeline([
 ```
 
 Every `LLMContextFrame` that flows through is enriched with relevant memories
-(as a system message) and mined for **new** turns to persist — then pushed on,
-enriched or not, on time.
+(as a system message) and its **new** user turns are sent to fact extraction —
+then pushed on, enriched or not, on time.
 
 ## Design guarantees
 
 - **Budgeted recall.** Enrichment runs under a hard timeout (default
   **1.2 s**). A slow or dead memory backend means an unenriched frame, never a
   stalled voice reply.
-- **Immediate, loss-proof capture.** Every new message is sent the moment
-  its frame passes — the current utterance is in flight BEFORE the LLM
-  replies, so a disconnect can never lose it. Junk filtering and fact
-  extraction happen server-side (the platform's low-value gate +
-  conversational ingestion): the memory store receives curated facts,
-  not transcript clutter.
-- **Delta-only capture.** Only messages *not seen before* are stored, tracked
-  by deterministic idempotency seeds. Growing a 50-message context does not
-  re-store 50 messages per turn.
-- **Injection exclusion.** The memory block this service adds is never captured
-  back as a new memory.
-- **Graceful end, salvaged abort.** On `EndFrame`, queued writes get a bounded
-  window (3 s) to land before the pipeline stops — the call's final exchange is
-  not lost. On `CancelFrame`, the frame is pushed first and writes get a brief
+- **Immediate, loss-proof capture.** Every new user message is sent the
+  moment its frame passes — the current utterance is in flight BEFORE the
+  LLM replies, so a disconnect can never lose it. Filler filtering and fact
+  extraction happen server-side: only the durable facts in what the caller
+  said are stored as memories, not the turn text.
+- **Delta-only capture.** Only user messages *not seen before* are sent,
+  tracked by deterministic idempotency seeds; a retried turn is recognised
+  server-side and not extracted twice. Growing a 50-message context does not
+  re-send 50 messages per turn.
+- **Injection exclusion.** The memory block this service adds is never sent
+  back as a new turn.
+- **Graceful end, salvaged abort.** On `EndFrame`, queued sends get a bounded
+  window (3 s) to land before the pipeline stops — the caller's last words are
+  not lost. On `CancelFrame`, the frame is pushed first and sends get a brief
   salvage window.
 - **Failure-proof.** HTTP errors, quota limits, and timeouts all degrade to
   "no memories this turn". Nothing propagates into the pipeline.
@@ -147,10 +147,15 @@ memory = MemorySyncMemoryService(
 
 ## Semantics worth knowing
 
-- Both **user and assistant** turns are persisted, with role fidelity.
-- Idempotency seeds make retries/reconnects duplicate-free server-side.
+- Only the caller's (**user**) turns are sent, as plain text with
+  `role: "user"`. The server extracts the durable facts they contain and
+  stores only those, tagged with `session_id: "pipecat::<session>"`.
+  Assistant replies are not sent — they are not stored as memories — and
+  filler such as "ok" or "thanks" stores nothing.
+- Idempotency seeds let the server recognise retries and reconnects: the same
+  turn is not extracted twice.
 - Free-tier quota exhaustion is silent by design (empty recall, accepted-but-
-  dropped writes); evaluation keys surface strict `429`s instead.
+  skipped sends); evaluation keys surface strict `429`s instead.
 - The service is reusable across pipeline runs; call `await memory.aclose()`
   from application shutdown if you want an explicit flush + client close.
 
@@ -158,7 +163,7 @@ memory = MemorySyncMemoryService(
 
 ```bash
 python -m venv venv && venv/Scripts/pip install -e . pipecat-ai pytest pytest-asyncio
-venv/Scripts/python -m pytest tests -q    # 14 tests, run via pipecat's official test harness
+venv/Scripts/python -m pytest tests -q    # 19 tests, run via pipecat's official test harness
 ```
 
 ## Docs

{pipecat_memorysync-1.1.1 → pipecat_memorysync-1.2.0}/README.md

@@ -1,146 +1,151 @@
-# memorysync-pipecat
-
-[MemorySync](https://memorysync.io) for [Pipecat](https://github.com/pipecat-ai/pipecat) —
-long-term memory for voice pipelines that never stalls a reply and never
-re-stores what it already knows. PyPI package: **`pipecat-memorysync`**.
-
-Built and maintained by the [MemorySync](https://memorysync.io) team —
-MemorySync is our product, and this integration is actively maintained
-alongside it.
-
-**Tested with Pipecat v1.8.1** (`pipecat-ai>=1.0.0,<2`).
-
-```bash
-pip install pipecat-memorysync
-# or
-uv add pipecat-memorysync
-```
-
-## Where it sits
-
-`MemorySyncMemoryService` is a `FrameProcessor`. Place it **between your
-context aggregator and your LLM service**:
-
-```
-transport.input() → stt → context_aggregator.user()
-    → MemorySyncMemoryService        ← enriches + captures here
-    → llm → tts → transport.output() → context_aggregator.assistant()
-```
-
-```python
-from pipecat_memorysync import MemorySyncMemoryService
-
-memory = MemorySyncMemoryService(
-    api_key="ms_...",                 # or MEMORYSYNC_API_KEY env var
-    user_id="caller-42",              # stable end-user id
-    session_id="call-123",            # optional: scope to this call
-)
-
-pipeline = Pipeline([
-    transport.input(),
-    stt,
-    context_aggregator.user(),
-    memory,
-    llm,
-    tts,
-    transport.output(),
-    context_aggregator.assistant(),
-])
-```
-
-Every `LLMContextFrame` that flows through is enriched with relevant memories
-(as a system message) and mined for **new** turns to persist — then pushed on,
-enriched or not, on time.
-
-## Design guarantees
-
-- **Budgeted recall.** Enrichment runs under a hard timeout (default
-  **1.2 s**). A slow or dead memory backend means an unenriched frame, never a
-  stalled voice reply.
-- **Immediate, loss-proof capture.** Every new message is sent the moment
-  its frame passes — the current utterance is in flight BEFORE the LLM
-  replies, so a disconnect can never lose it. Junk filtering and fact
-  extraction happen server-side (the platform's low-value gate +
-  conversational ingestion): the memory store receives curated facts,
-  not transcript clutter.
-- **Delta-only capture.** Only messages *not seen before* are stored, tracked
-  by deterministic idempotency seeds. Growing a 50-message context does not
-  re-store 50 messages per turn.
-- **Injection exclusion.** The memory block this service adds is never captured
-  back as a new memory.
-- **Graceful end, salvaged abort.** On `EndFrame`, queued writes get a bounded
-  window (3 s) to land before the pipeline stops — the call's final exchange is
-  not lost. On `CancelFrame`, the frame is pushed first and writes get a brief
-  salvage window.
-- **Failure-proof.** HTTP errors, quota limits, and timeouts all degrade to
-  "no memories this turn". Nothing propagates into the pipeline.
-
-## Running the example
-
-A single-file voice agent that remembers callers across calls lives in
-[`examples/foundational.py`](examples/foundational.py):
-
-```bash
-uv add pipecat-memorysync "pipecat-ai[deepgram,cartesia,openai,silero,runner,webrtc]"
-
-export MEMORYSYNC_API_KEY=ms_...   # https://app.memorysync.io
-export DEEPGRAM_API_KEY=...
-export CARTESIA_API_KEY=...
-export OPENAI_API_KEY=...
-
-python examples/foundational.py
-```
-
-Open `http://localhost:7860/client`, tell the bot your name and a preference,
-hang up, and connect again — it remembers.
-
-## Configuration (`InputParams`)
-
-```python
-from pipecat_memorysync import MemorySyncMemoryService
-
-memory = MemorySyncMemoryService(
-    api_key="ms_...",
-    user_id="caller-42",
-    params=MemorySyncMemoryService.InputParams(
-        top_k=5,                  # memories injected per turn
-        recall_timeout=1.2,       # hard budget, seconds
-        add_as_system_message=True,
-        position="end",           # where the memory block lands in the context
-        min_prompt_chars=8,       # skip enrichment for shorter user prompts
-    ),
-)
-```
-
-| Param | Default | Meaning |
-| --- | --- | --- |
-| `top_k` | `5` | Memories injected per turn |
-| `recall_timeout` | `1.2` | Hard recall budget in seconds |
-| `system_prompt` | (guarded header) | Prefix line for the injected block; also the capture-exclusion marker |
-| `add_as_system_message` | `True` | Inject as `system` (else appended to the latest user message) |
-| `position` | `"end"` | `"start"` or `"end"` of the message list |
-| `min_prompt_chars` | `8` | Skip recall for trivial prompts |
-
-## Semantics worth knowing
-
-- Both **user and assistant** turns are persisted, with role fidelity.
-- Idempotency seeds make retries/reconnects duplicate-free server-side.
-- Free-tier quota exhaustion is silent by design (empty recall, accepted-but-
-  dropped writes); evaluation keys surface strict `429`s instead.
-- The service is reusable across pipeline runs; call `await memory.aclose()`
-  from application shutdown if you want an explicit flush + client close.
-
-## Development
-
-```bash
-python -m venv venv && venv/Scripts/pip install -e . pipecat-ai pytest pytest-asyncio
-venv/Scripts/python -m pytest tests -q    # 14 tests, run via pipecat's official test harness
-```
-
-## Docs
-
-Full guide: [docs.memorysync.io/guides/pipecat](https://docs.memorysync.io/guides/pipecat)
-
-## License
-
-MIT
+# memorysync-pipecat
+
+[MemorySync](https://memorysync.io) for [Pipecat](https://github.com/pipecat-ai/pipecat) —
+long-term memory for voice pipelines that never stalls a reply and never
+re-sends a turn it already sent. PyPI package: **`pipecat-memorysync`**.
+
+Built and maintained by the [MemorySync](https://memorysync.io) team —
+MemorySync is our product, and this integration is actively maintained
+alongside it.
+
+**Tested with Pipecat v1.8.1** (`pipecat-ai>=1.0.0,<2`).
+
+```bash
+pip install pipecat-memorysync
+# or
+uv add pipecat-memorysync
+```
+
+## Where it sits
+
+`MemorySyncMemoryService` is a `FrameProcessor`. Place it **between your
+context aggregator and your LLM service**:
+
+```
+transport.input() → stt → context_aggregator.user()
+    → MemorySyncMemoryService        ← enriches + captures here
+    → llm → tts → transport.output() → context_aggregator.assistant()
+```
+
+```python
+from pipecat_memorysync import MemorySyncMemoryService
+
+memory = MemorySyncMemoryService(
+    api_key="ms_...",                 # or MEMORYSYNC_API_KEY env var
+    user_id="caller-42",              # stable end-user id
+    session_id="call-123",            # optional: scope to this call
+)
+
+pipeline = Pipeline([
+    transport.input(),
+    stt,
+    context_aggregator.user(),
+    memory,
+    llm,
+    tts,
+    transport.output(),
+    context_aggregator.assistant(),
+])
+```
+
+Every `LLMContextFrame` that flows through is enriched with relevant memories
+(as a system message) and its **new** user turns are sent to fact extraction —
+then pushed on, enriched or not, on time.
+
+## Design guarantees
+
+- **Budgeted recall.** Enrichment runs under a hard timeout (default
+  **1.2 s**). A slow or dead memory backend means an unenriched frame, never a
+  stalled voice reply.
+- **Immediate, loss-proof capture.** Every new user message is sent the
+  moment its frame passes — the current utterance is in flight BEFORE the
+  LLM replies, so a disconnect can never lose it. Filler filtering and fact
+  extraction happen server-side: only the durable facts in what the caller
+  said are stored as memories, not the turn text.
+- **Delta-only capture.** Only user messages *not seen before* are sent,
+  tracked by deterministic idempotency seeds; a retried turn is recognised
+  server-side and not extracted twice. Growing a 50-message context does not
+  re-send 50 messages per turn.
+- **Injection exclusion.** The memory block this service adds is never sent
+  back as a new turn.
+- **Graceful end, salvaged abort.** On `EndFrame`, queued sends get a bounded
+  window (3 s) to land before the pipeline stops — the caller's last words are
+  not lost. On `CancelFrame`, the frame is pushed first and sends get a brief
+  salvage window.
+- **Failure-proof.** HTTP errors, quota limits, and timeouts all degrade to
+  "no memories this turn". Nothing propagates into the pipeline.
+
+## Running the example
+
+A single-file voice agent that remembers callers across calls lives in
+[`examples/foundational.py`](examples/foundational.py):
+
+```bash
+uv add pipecat-memorysync "pipecat-ai[deepgram,cartesia,openai,silero,runner,webrtc]"
+
+export MEMORYSYNC_API_KEY=ms_...   # https://app.memorysync.io
+export DEEPGRAM_API_KEY=...
+export CARTESIA_API_KEY=...
+export OPENAI_API_KEY=...
+
+python examples/foundational.py
+```
+
+Open `http://localhost:7860/client`, tell the bot your name and a preference,
+hang up, and connect again — it remembers.
+
+## Configuration (`InputParams`)
+
+```python
+from pipecat_memorysync import MemorySyncMemoryService
+
+memory = MemorySyncMemoryService(
+    api_key="ms_...",
+    user_id="caller-42",
+    params=MemorySyncMemoryService.InputParams(
+        top_k=5,                  # memories injected per turn
+        recall_timeout=1.2,       # hard budget, seconds
+        add_as_system_message=True,
+        position="end",           # where the memory block lands in the context
+        min_prompt_chars=8,       # skip enrichment for shorter user prompts
+    ),
+)
+```
+
+| Param | Default | Meaning |
+| --- | --- | --- |
+| `top_k` | `5` | Memories injected per turn |
+| `recall_timeout` | `1.2` | Hard recall budget in seconds |
+| `system_prompt` | (guarded header) | Prefix line for the injected block; also the capture-exclusion marker |
+| `add_as_system_message` | `True` | Inject as `system` (else appended to the latest user message) |
+| `position` | `"end"` | `"start"` or `"end"` of the message list |
+| `min_prompt_chars` | `8` | Skip recall for trivial prompts |
+
+## Semantics worth knowing
+
+- Only the caller's (**user**) turns are sent, as plain text with
+  `role: "user"`. The server extracts the durable facts they contain and
+  stores only those, tagged with `session_id: "pipecat::<session>"`.
+  Assistant replies are not sent — they are not stored as memories — and
+  filler such as "ok" or "thanks" stores nothing.
+- Idempotency seeds let the server recognise retries and reconnects: the same
+  turn is not extracted twice.
+- Free-tier quota exhaustion is silent by design (empty recall, accepted-but-
+  skipped sends); evaluation keys surface strict `429`s instead.
+- The service is reusable across pipeline runs; call `await memory.aclose()`
+  from application shutdown if you want an explicit flush + client close.
+
+## Development
+
+```bash
+python -m venv venv && venv/Scripts/pip install -e . pipecat-ai pytest pytest-asyncio
+venv/Scripts/python -m pytest tests -q    # 19 tests, run via pipecat's official test harness
+```
+
+## Docs
+
+Full guide: [docs.memorysync.io/guides/pipecat](https://docs.memorysync.io/guides/pipecat)
+
+## License
+
+MIT