Metadata-Version: 2.5
Name: bedrock-memorysync
Version: 1.0.0
Summary: MemorySync reference architecture for AWS Bedrock agents: a memory-augmented Converse loop and a Bedrock Agents action-group Lambda — the first vendor action-group memory integration.
Project-URL: Homepage, https://memorysync.io
Project-URL: Documentation, https://docs.memorysync.io/guides/bedrock
Project-URL: Changelog, https://docs.memorysync.io/release-notes
Author-email: MemorySync <support@memorysync.io>
License-Expression: MIT
Keywords: agents,ai,aws,bedrock,bedrock-agents,converse,memory,memorysync
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.25
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == 'aws'
Description-Content-Type: text/markdown

# bedrock-memorysync

MemorySync reference architecture for **AWS Bedrock** agents — two runnable
patterns:

1. **`MemoryConverseLoop`** — a memory-augmented `bedrock-runtime.converse`
   loop: recall injected as a system block under a hard budget, both turns
   persisted with idempotent seeds.
2. **Bedrock Agents action group** — a Lambda handler + function schema that
   gives any Bedrock Agent four memory functions. **No memory vendor
   (including Mem0) ships a Bedrock Agents action-group integration — this
   is the first.**

```bash
pip install bedrock-memorysync
```

## Pattern 1 — the Converse loop

```python
import boto3
from bedrock_memorysync import MemoryConverseLoop

loop = MemoryConverseLoop(
    bedrock_client=boto3.client("bedrock-runtime"),
    model_id="anthropic.claude-3-haiku-20240307-v1:0",
    user_id="customer-42",                       # required
    system_prompt="You are a helpful travel assistant.",
)
loop.chat("I always prefer window seats on long flights")
# … a new session, days later:
loop.new_session("support-2")
loop.chat("which seat should I book for the Oslo flight?")   # remembers
```

- Recall runs under `recall_timeout` (default **1.2 s**) and fails open to a
  memory-free turn — memory can never delay or break the model call.
- Turns persist AFTER the reply with deterministic seeds — retries converge.
- You own the boto3 client (region, credentials, retry policy) — tests drive
  it with botocore's `Stubber`.

## Pattern 2 — Bedrock Agents action group

Deploy the Lambda (SAM):

```bash
sam deploy --guided --parameter-overrides MemorySyncApiKey=ms_...
```

Attach to your agent (function-details schema, importable):

```python
from bedrock_memorysync import FUNCTION_SCHEMA

bedrock_agent.create_agent_action_group(
    agentId=agent_id, agentVersion="DRAFT",
    actionGroupName="memorysync-memory",
    actionGroupExecutor={"lambda": function_arn},
    functionSchema={"functions": FUNCTION_SCHEMA},
)
```

| Function | What it does |
|---|---|
| `remember` | store a fact/turn (idempotent — agent retries never duplicate) |
| `recall_context` | prompt-ready block of relevant memories |
| `search_memories` | scored JSON list (≤25) |
| `forget_memory` | delete exactly ONE memory by id, loudly |

There is deliberately **no delete-everything function** — a model-reachable
account wipe is a data-loss foot-gun.

**Identity ladder (multi-tenant safe):** `sessionAttributes.memorysync_user_id`
(set by your app when invoking the agent) → a `user_id` parameter → the
Bedrock `sessionId`. Every failure returns a structured
`responseState: FAILURE` body the agent can react to — never an unhandled
Lambda error surfaced as a wall of text.

## Why not the alternatives?

| | AWS AgentCore Memory | Mem0 | **MemorySync** |
|---|---|---|---|
| Bedrock Agents action group | n/a (separate runtime) | ✗ none | ✅ first and only |
| Setup | control-plane resource + strategy activation polling (`sleep(10)` loops) | ✗ OSS-only sidecar: self-hosted Mem0 + **OpenSearch you operate** ($80–200+/mo) | ✅ one API key |
| Extraction control | ✗ black-box strategies | your own infra | ✅ managed pipeline, server-side gating |
| Cross-platform recall | ✗ AWS-only (`actorId` inside one account) | ⚠ self-hosted API | ✅ the same memories in LangChain, Flowise, Dify, voice agents… |
| Portability | ✗ total AWS lock-in | ⚠ | ✅ works with any cloud + Bedrock |
| Pricing | 12-component consumption billing | infra + ops | ✅ flat SaaS plans |

## Tests

```bash
pip install -e . boto3 pytest
pytest tests -q   # 28 checks
```

The suite drives the REAL boto3 client under botocore's `Stubber`
(system-block injection asserted verbatim) and the Lambda handler with the
documented Bedrock Agents event shapes — including the identity ladder,
idempotent retries, FAILURE response states, and quota modes.

## License

MIT © MemorySync.
